]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*- |
2 | // vim: ts=8 sw=2 smarttab | |
3 | /* | |
4 | * Ceph - scalable distributed file system | |
5 | * | |
6 | * Copyright (C) 2004-2006 Sage Weil <sage@newdream.net> | |
7 | * | |
8 | * This is free software; you can redistribute it and/or | |
9 | * modify it under the terms of the GNU Lesser General Public | |
10 | * License version 2.1, as published by the Free Software | |
11 | * Foundation. See file COPYING. | |
12 | * | |
13 | */ | |
14 | ||
15 | ||
16 | #ifndef CEPH_DISPATCHER_H | |
17 | #define CEPH_DISPATCHER_H | |
18 | ||
19 | #include "include/assert.h" | |
28e407b8 | 20 | #include <memory> |
7c673cae FG |
21 | #include "include/buffer_fwd.h" |
22 | #include "include/assert.h" | |
23 | ||
24 | class Messenger; | |
25 | class Message; | |
26 | class Connection; | |
27 | class AuthAuthorizer; | |
28 | class CryptoKey; | |
29 | class CephContext; | |
28e407b8 | 30 | class AuthAuthorizerChallenge; |
7c673cae FG |
31 | |
32 | class Dispatcher { | |
33 | public: | |
34 | explicit Dispatcher(CephContext *cct_) | |
35 | : cct(cct_) | |
36 | { | |
37 | } | |
38 | virtual ~Dispatcher() { } | |
39 | ||
40 | /** | |
41 | * The Messenger calls this function to query if you are capable | |
42 | * of "fast dispatch"ing a message. Indicating that you can fast | |
43 | * dispatch it requires that you: | |
44 | * 1) Handle the Message quickly and without taking long-term contended | |
45 | * locks. (This function is likely to be called in-line with message | |
46 | * receipt.) | |
47 | * 2) Be able to accept the Message even if you have not yet received | |
48 | * an ms_handle_accept() notification for the Connection it is associated | |
49 | * with, and even if you *have* called mark_down() or received an | |
50 | * ms_handle_reset() (or similar) call on the Connection. You will | |
51 | * not receive more than one dead "message" (and should generally be | |
52 | * prepared for that circumstance anyway, since the normal dispatch can begin, | |
53 | * then trigger Connection failure before it's percolated through your system). | |
54 | * We provide ms_handle_fast_[connect|accept] calls if you need them, under | |
55 | * similar speed and state constraints as fast_dispatch itself. | |
56 | * 3) Be able to make a determination on fast_dispatch without relying | |
57 | * on particular system state -- the ms_can_fast_dispatch() call might | |
58 | * be called multiple times on a single message; the state might change between | |
59 | * calling ms_can_fast_dispatch and ms_fast_dispatch; etc. | |
60 | * | |
61 | * @param m The message we want to fast dispatch. | |
62 | * @returns True if the message can be fast dispatched; false otherwise. | |
63 | */ | |
64 | virtual bool ms_can_fast_dispatch(const Message *m) const { return false;} | |
65 | /** | |
66 | * This function determines if a dispatcher is included in the | |
67 | * list of fast-dispatch capable Dispatchers. | |
68 | * @returns True if the Dispatcher can handle any messages via | |
69 | * fast dispatch; false otherwise. | |
70 | */ | |
71 | virtual bool ms_can_fast_dispatch_any() const { return false; } | |
72 | /** | |
73 | * Perform a "fast dispatch" on a given message. See | |
74 | * ms_can_fast_dispatch() for the requirements. | |
75 | * | |
76 | * @param m The Message to fast dispatch. | |
77 | */ | |
78 | virtual void ms_fast_dispatch(Message *m) { ceph_abort(); } | |
79 | /** | |
80 | * Let the Dispatcher preview a Message before it is dispatched. This | |
81 | * function is called on *every* Message, prior to the fast/regular dispatch | |
82 | * decision point, but it is only used on fast-dispatch capable systems. An | |
83 | * implementation of ms_fast_preprocess must be essentially lock-free in the | |
84 | * same way as the ms_fast_dispatch function is (in particular, ms_fast_preprocess | |
85 | * may be called while the Messenger holds internal locks that prevent progress from | |
86 | * other threads, so any locks it takes must be at the very bottom of the hierarchy). | |
87 | * Messages are delivered in receipt order within a single Connection, but there are | |
88 | * no guarantees across Connections. This makes it useful for some limited | |
89 | * coordination between Messages which can be fast_dispatch'ed and those which must | |
90 | * go through normal dispatch. | |
91 | * | |
92 | * @param m A message which has been received | |
93 | */ | |
94 | virtual void ms_fast_preprocess(Message *m) {} | |
95 | /** | |
96 | * The Messenger calls this function to deliver a single message. | |
97 | * | |
98 | * @param m The message being delivered. You (the Dispatcher) | |
99 | * are given a single reference count on it. | |
100 | */ | |
101 | virtual bool ms_dispatch(Message *m) = 0; | |
102 | ||
103 | /** | |
104 | * This function will be called whenever a Connection is newly-created | |
105 | * or reconnects in the Messenger. | |
106 | * | |
107 | * @param con The new Connection which has been established. You are not | |
108 | * granted a reference to it -- take one if you need one! | |
109 | */ | |
110 | virtual void ms_handle_connect(Connection *con) {} | |
111 | ||
112 | /** | |
113 | * This function will be called synchronously whenever a Connection is | |
114 | * newly-created or reconnects in the Messenger, if you support fast | |
115 | * dispatch. It is guaranteed to be called before any messages are | |
116 | * dispatched. | |
117 | * | |
118 | * @param con The new Connection which has been established. You are not | |
119 | * granted a reference to it -- take one if you need one! | |
120 | */ | |
121 | virtual void ms_handle_fast_connect(Connection *con) {} | |
122 | ||
123 | /** | |
124 | * Callback indicating we have accepted an incoming connection. | |
125 | * | |
126 | * @param con The (new or existing) Connection associated with the session | |
127 | */ | |
128 | virtual void ms_handle_accept(Connection *con) {} | |
129 | ||
130 | /** | |
131 | * Callback indicating we have accepted an incoming connection, if you | |
132 | * support fast dispatch. It is guaranteed to be called before any messages | |
133 | * are dispatched. | |
134 | * | |
135 | * @param con The (new or existing) Connection associated with the session | |
136 | */ | |
137 | virtual void ms_handle_fast_accept(Connection *con) {} | |
138 | ||
139 | /* | |
140 | * this indicates that the ordered+reliable delivery semantics have | |
141 | * been violated. Messages may have been lost due to a fault | |
142 | * in the network connection. | |
143 | * Only called on lossy Connections. | |
144 | * | |
145 | * @param con The Connection which broke. You are not granted | |
146 | * a reference to it. | |
147 | */ | |
148 | virtual bool ms_handle_reset(Connection *con) = 0; | |
149 | ||
150 | /** | |
151 | * This indicates that the ordered+reliable delivery semantics | |
152 | * have been violated because the remote somehow reset. | |
153 | * It implies that incoming messages were dropped, and | |
154 | * probably some of our previous outgoing messages were too. | |
155 | * | |
156 | * @param con The Connection which broke. You are not granted | |
157 | * a reference to it. | |
158 | */ | |
159 | virtual void ms_handle_remote_reset(Connection *con) = 0; | |
160 | ||
161 | /** | |
162 | * This indicates that the connection is both broken and further | |
163 | * connection attempts are failing because other side refuses | |
164 | * it. | |
165 | * | |
166 | * @param con The Connection which broke. You are not granted | |
167 | * a reference to it. | |
168 | */ | |
169 | virtual bool ms_handle_refused(Connection *con) = 0; | |
170 | ||
171 | /** | |
172 | * @defgroup Authentication | |
173 | * @{ | |
174 | */ | |
175 | /** | |
176 | * Retrieve the AuthAuthorizer for the given peer type. It might not | |
177 | * provide one if it knows there is no AuthAuthorizer for that type. | |
178 | * | |
179 | * @param dest_type The peer type we want the authorizer for. | |
180 | * @param a Double pointer to an AuthAuthorizer. The Dispatcher will fill | |
181 | * in *a with the correct AuthAuthorizer, if it can. Make sure that you have | |
182 | * set *a to NULL before calling in. | |
183 | * @param force_new Force the Dispatcher to wait for a new set of keys before | |
184 | * returning the authorizer. | |
185 | * | |
186 | * @return True if this function call properly filled in *a, false otherwise. | |
187 | */ | |
188 | virtual bool ms_get_authorizer(int dest_type, AuthAuthorizer **a, bool force_new) { return false; } | |
189 | /** | |
190 | * Verify the authorizer for a new incoming Connection. | |
191 | * | |
192 | * @param con The new incoming Connection | |
193 | * @param peer_type The type of the endpoint which initiated this Connection | |
194 | * @param protocol The ID of the protocol in use (at time of writing, cephx or none) | |
195 | * @param authorizer The authorization string supplied by the remote | |
196 | * @param authorizer_reply Output param: The string we should send back to | |
197 | * the remote to authorize ourselves. Only filled in if isvalid | |
198 | * @param isvalid Output param: True if authorizer is valid, false otherwise | |
199 | * | |
200 | * @return True if we were able to prove or disprove correctness of | |
201 | * authorizer, false otherwise. | |
202 | */ | |
203 | virtual bool ms_verify_authorizer(Connection *con, | |
204 | int peer_type, | |
205 | int protocol, | |
206 | ceph::bufferlist& authorizer, | |
207 | ceph::bufferlist& authorizer_reply, | |
208 | bool& isvalid, | |
28e407b8 AA |
209 | CryptoKey& session_key, |
210 | std::unique_ptr<AuthAuthorizerChallenge> *challenge) { | |
211 | return false; | |
212 | } | |
7c673cae FG |
213 | /** |
214 | * @} //Authentication | |
215 | */ | |
216 | protected: | |
217 | CephContext *cct; | |
218 | private: | |
219 | explicit Dispatcher(const Dispatcher &rhs); | |
220 | Dispatcher& operator=(const Dispatcher &rhs); | |
221 | }; | |
222 | ||
223 | #endif |