ceph/src/msg/Dispatcher.h

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