core/library/processes/mail_stop.h

   1 #ifndef MAIL_STOP_CLASS
   2 #define MAIL_STOP_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : mail_stop                                                         *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1998-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include "safe_callback.h"
  19
  20 #include <structures/unique_id.h>
  21
  22 namespace processes {
  23
  24 // forward:
  25 class letter;
  26
  27 //! Base class for routes on which letters are automatically delivered.
  28 /*!
  29   The letters will show up for a particular unique id at this mail stop.
  30   They are delivered by the object serving as the post office.
  31 */
  32
  33 class mail_stop : public safe_callback
  34 {
  35 public:
  36
  37   // it is required that the derived mail_stop invoke the end_availability()
  38   // method in its destructor before it destroys any other objects.
  39
  40   class items_to_deliver : public callback_data_block {
  41   public:
  42     items_to_deliver(const structures::unique_int &id, letter *package)
  43         : _id(id), _package(package) {}
  44     const structures::unique_int &_id;
  45     letter *_package;
  46   };
  47
  48   virtual void delivery_for_you(const structures::unique_int &id, letter *package) = 0;
  49     //!< the derived object must provide this function.
  50     /*!< prompts the recipient with the "id" to accept delivery of a "package".
  51     the package can be modified as desired and MUST be recycled before
  52     returning from this function.
  53     IMPORTANT NOTE: the receiver MUST be thread-safe with respect to the
  54     objects that it uses to handle this delivery!  this is because mail is
  55     delivered on a thread other than the main program thread. */
  56
  57 protected:
  58   //! invoked by the safe callback machinery.
  59   /*! this is implemented in this class and merely re-routes the call to the
  60   more specific delivery_for_you() method. */
  61   virtual void real_callback(callback_data_block &data) {
  62     items_to_deliver *bits = dynamic_cast<items_to_deliver *>(&data);
  63     if (!bits) return;  // bad type.
  64     delivery_for_you(bits->_id, bits->_package);
  65   }
  66
  67 };
  68
  69 } //namespace.
  70
  71 #endif
  72