new fortune
[feisty_meow.git] / nucleus / library / processes / mailbox.h
1 #ifndef MAILBOX_CLASS
2 #define MAILBOX_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : mailbox                                                           *
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 <basis/mutex.h>
19 #include <structures/set.h>
20 #include <structures/unique_id.h>
21
22 namespace processes {
23
24 class letter;
25 class mailbox_bank;
26
27 //! Implements a thread safe "mail" delivery system.
28 /*!
29   Senders can drop packages off into the mailbox and the receivers can get
30   those packages back out of it.  The base class for all mail items is also
31   provided in this library (letter.h).  The name of this object is slightly
32   misleading; this object is really more of a post office.  Each unique id
33   has its own mailbox slot for receiving mail.
34 */
35
36 class mailbox : public virtual basis::root_object
37 {
38 public:
39   mailbox();
40   virtual ~mailbox();
41
42   void drop_off(const structures::unique_int &id, letter *package);
43     //!< drops a "package" in the mailbox for "id".
44     /*!< note that when you send a package to someone, you give up all
45     authority and control over that package.  hopefully the end recipient
46     will eventually pick it up and then delete it.  if the package is never
47     received, then this object will delete it. */
48
49   bool pick_up(const structures::unique_int &id, letter * &package);
50     //!< returns true if the mailbox for "id" had a "package" to be delivered.
51     /*!< don't forget to check multiple times on a true outcome, since there
52     could be more than one package waiting.  false is returned when no more
53     mail is waiting.  be careful; "package" could be a bomb.  dynamic casts
54     seem appropriate as a method for ensuring that you get the type of
55     object you expect.  note that once the invoker receives a package, it
56     is their responsibility to carefully manage it and then delete the
57     package after handling.  not deleting the "package" pointer is grounds
58     for memory leaks. */
59
60   int waiting(const structures::unique_int &id) const;
61     //!< returns the number of items waiting for the "id" specified, if any.
62
63   void get_ids(structures::int_set &to_fill);
64     //!< stuffs the set "to_fill" with the ids of all mailboxes present.
65     /*!< if you want only those mailboxes holding one or more letters, then
66     call the clean_up() method prior to this method. */
67
68   bool close_out(const structures::unique_int &id);
69     //!< dumps all packages stored for the "id" and shuts down its mailbox.
70     /*!< the destructors for those packages should never try to do anything
71     with the mailbox system or a deadlock could result.  true is returned if
72     the "id" had a registered mailbox; false just indicates there was no box
73     to clear up. */
74
75   void show(basis::astring &to_fill);
76     //!< provides a picture of what's waiting in the mailbox.
77     /*!< this relies on the derived letter's required text_form() function. */
78
79   void clean_up();
80     //!< removes any empty mailboxes from our list.
81
82   void limit_boxes(int max_letters);
83     //!< establishes a limit on the number of letters.
84     /*!< this is a helper function for a very special mailbox; it has a
85     limited maximum size and any letters above the "max_letters" count will
86     be deleted.  don't use this function on any mailbox where all letters
87     are important; your mailbox must have a notion of unreliability before
88     this would ever be appropriate. */
89
90   enum apply_outcomes {
91     OKAY = basis::common::OKAY,   //!< continue apply process.
92
93     DEFINE_OUTCOME(APPLY_STOP, -46, "Halt the apply process"),
94     DEFINE_OUTCOME(APPLY_WHACK, -47, "Removes the current letter, but "
95         "continues"),
96     DEFINE_OUTCOME(APPLY_WHACK_STOP, -48, "Halts apply and trashes the "
97         "current letter")
98   };
99
100   typedef basis::outcome apply_function(letter &current, int uid, void *data_link);
101     //!< the "apply_function" is what a user of apply() must provide.
102     /*!< the function will be called on every letter in the mailbox unless one
103     of the invocations returns APPLY_STOP or APPLY_WHACK_STOP; this causes
104     the apply process to stop (and zap the node for APPLY_WHACK).  the "uid"
105     is the target for the "current" letter.  the "data_link" provides a way
106     for the function to refer back to a parent class or data package of some
107     sort.  note that all sorts of deadlocks will occur if your apply
108     function tries to do anything on the mailbox, even transitively.  keep
109     those functions as simple as possible. */
110
111   void apply(apply_function *to_apply, void *data_link);
112     //!< calls the "to_apply" function on possibly every letter in the mailbox.
113     /*!< this iterates until the function returns a 'STOP' outcome.  the
114     "data_link" pointer is passed to the apply function.  NOTE: it is NOT safe
115     to rearrange or manipulate the mailbox in any way from your "to_apply"
116     function; the only changes allowed are those caused by the return value
117     from "to_apply". */
118
119 private:
120   basis::mutex *_transaction_lock;  //!< keeps the state of the mailbox safe.
121   mailbox_bank *_packages;  //!< the collection of mail that has arrived.
122
123   // prohibited.
124   mailbox(const mailbox &);
125   mailbox &operator =(const mailbox &);
126 };
127
128 } //namespace.
129
130 #endif
131