new fortune
[feisty_meow.git] / nucleus / 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