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 <memory>
  20 #include "include/buffer_fwd.h"
  21 #include "include/ceph_assert.h"
  22 #include "include/common_fwd.h"
  23 #include "msg/MessageRef.h"
  24
  25 class Messenger;
  26 class Connection;
  27 class CryptoKey;
  28 class KeyStore;
  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   virtual bool ms_can_fast_dispatch2(const MessageConstRef& m) const {
  64     return ms_can_fast_dispatch(m.get());
  65   }
  66   /**
  67    * This function determines if a dispatcher is included in the
  68    * list of fast-dispatch capable Dispatchers.
  69    * @returns True if the Dispatcher can handle any messages via
  70    * fast dispatch; false otherwise.
  71    */
  72   virtual bool ms_can_fast_dispatch_any() const { return false; }
  73   /**
  74    * Perform a "fast dispatch" on a given message. See
  75    * ms_can_fast_dispatch() for the requirements.
  76    *
  77    * @param m The Message to fast dispatch.
  78    */
  79   virtual void ms_fast_dispatch(Message *m) { ceph_abort(); }
  80
  81   /* ms_fast_dispatch2 because otherwise the child must define both */
  82   virtual void ms_fast_dispatch2(const MessageRef &m) {
  83     /* allow old style dispatch handling that expects a Message * with a floating ref */
  84     return ms_fast_dispatch(MessageRef(m).detach()); /* XXX N.B. always consumes ref */
  85   }
  86
  87   /**
  88    * Let the Dispatcher preview a Message before it is dispatched. This
  89    * function is called on *every* Message, prior to the fast/regular dispatch
  90    * decision point, but it is only used on fast-dispatch capable systems. An
  91    * implementation of ms_fast_preprocess must be essentially lock-free in the
  92    * same way as the ms_fast_dispatch function is (in particular, ms_fast_preprocess
  93    * may be called while the Messenger holds internal locks that prevent progress from
  94    * other threads, so any locks it takes must be at the very bottom of the hierarchy).
  95    * Messages are delivered in receipt order within a single Connection, but there are
  96    * no guarantees across Connections. This makes it useful for some limited
  97    * coordination between Messages which can be fast_dispatch'ed and those which must
  98    * go through normal dispatch.
  99    *
 100    * @param m A message which has been received
 101    */
 102   virtual void ms_fast_preprocess(Message *m) {}
 103
 104   /* ms_fast_preprocess2 because otherwise the child must define both */
 105   virtual void ms_fast_preprocess2(const MessageRef &m) {
 106     /* allow old style dispatch handling that expects a Message* */
 107     return ms_fast_preprocess(m.get());
 108   }
 109
 110   /**
 111    * The Messenger calls this function to deliver a single message.
 112    *
 113    * @param m The message being delivered. You (the Dispatcher)
 114    * are given a single reference count on it.
 115    */
 116   virtual bool ms_dispatch(Message *m) {
 117     ceph_abort();
 118   }
 119
 120   /* ms_dispatch2 because otherwise the child must define both */
 121   virtual bool ms_dispatch2(const MessageRef &m) {
 122     /* allow old style dispatch handling that expects a Message * with a floating ref */
 123     MessageRef mr(m);
 124     if (ms_dispatch(mr.get())) {
 125       mr.detach(); /* dispatcher consumed ref */
 126       return true;
 127     }
 128     return false;
 129   }
 130
 131   /**
 132    * This function will be called whenever a Connection is newly-created
 133    * or reconnects in the Messenger.
 134    *
 135    * @param con The new Connection which has been established. You are not
 136    * granted a reference to it -- take one if you need one!
 137    */
 138   virtual void ms_handle_connect(Connection *con) {}
 139
 140   /**
 141    * This function will be called synchronously whenever a Connection is
 142    * newly-created or reconnects in the Messenger, if you support fast
 143    * dispatch. It is guaranteed to be called before any messages are
 144    * dispatched.
 145    *
 146    * @param con The new Connection which has been established. You are not
 147    * granted a reference to it -- take one if you need one!
 148    */
 149   virtual void ms_handle_fast_connect(Connection *con) {}
 150
 151   /**
 152    * Callback indicating we have accepted an incoming connection.
 153    *
 154    * @param con The (new or existing) Connection associated with the session
 155    */
 156   virtual void ms_handle_accept(Connection *con) {}
 157
 158   /**
 159    * Callback indicating we have accepted an incoming connection, if you
 160    * support fast dispatch. It is guaranteed to be called before any messages
 161    * are dispatched.
 162    *
 163    * @param con The (new or existing) Connection associated with the session
 164    */
 165   virtual void ms_handle_fast_accept(Connection *con) {}
 166
 167   /*
 168    * this indicates that the ordered+reliable delivery semantics have
 169    * been violated.  Messages may have been lost due to a fault
 170    * in the network connection.
 171    * Only called on lossy Connections.
 172    *
 173    * @param con The Connection which broke. You are not granted
 174    * a reference to it.
 175    */
 176   virtual bool ms_handle_reset(Connection *con) = 0;
 177
 178   /**
 179    * This indicates that the ordered+reliable delivery semantics
 180    * have been violated because the remote somehow reset.
 181    * It implies that incoming messages were dropped, and
 182    * probably some of our previous outgoing messages were too.
 183    *
 184    * @param con The Connection which broke. You are not granted
 185    * a reference to it.
 186    */
 187   virtual void ms_handle_remote_reset(Connection *con) = 0;
 188
 189   /**
 190    * This indicates that the connection is both broken and further
 191    * connection attempts are failing because other side refuses
 192    * it.
 193    *
 194    * @param con The Connection which broke. You are not granted
 195    * a reference to it.
 196    */
 197   virtual bool ms_handle_refused(Connection *con) = 0;
 198
 199   /**
 200    * @defgroup Authentication
 201    * @{
 202    */
 203
 204   /**
 205    * handle successful authentication (msgr2)
 206    *
 207    * Authenticated result/state will be attached to the Connection. This is
 208    * called via the MonClient.
 209    *
 210    * Do not acquire locks in this method! It is considered "fast" delivery.
 211    *
 212    * return 1 for success
 213    * return 0 for no action (let another Dispatcher handle it)
 214    * return <0 for failure (failure to parse caps, for instance)
 215    */
 216   virtual int ms_handle_fast_authentication(Connection *con) {
 217     return 0;
 218   }
 219
 220   /**
 221    * @} //Authentication
 222    */
 223
 224 protected:
 225   CephContext *cct;
 226 private:
 227   explicit Dispatcher(const Dispatcher &rhs);
 228   Dispatcher& operator=(const Dispatcher &rhs);
 229 };
 230
 231 #endif