+++ /dev/null
-#ifndef MAILBOX_CLASS
-#define MAILBOX_CLASS
-
-/*****************************************************************************\
-* *
-* Name : mailbox *
-* Author : Chris Koeritz *
-* *
-*******************************************************************************
-* Copyright (c) 1998-$now By Author. This program is free software; you can *
-* redistribute it and/or modify it under the terms of the GNU General Public *
-* License as published by the Free Software Foundation; either version 2 of *
-* the License or (at your option) any later version. This is online at: *
-* http://www.fsf.org/copyleft/gpl.html *
-* Please send any updates to: fred@gruntose.com *
-\*****************************************************************************/
-
-#include <basis/mutex.h>
-#include <structures/set.h>
-#include <structures/unique_id.h>
-
-namespace processes {
-
-class letter;
-class mailbox_bank;
-
-//! Implements a thread safe "mail" delivery system.
-/*!
- Senders can drop packages off into the mailbox and the receivers can get
- those packages back out of it. The base class for all mail items is also
- provided in this library (letter.h). The name of this object is slightly
- misleading; this object is really more of a post office. Each unique id
- has its own mailbox slot for receiving mail.
-*/
-
-class mailbox : public virtual basis::root_object
-{
-public:
- mailbox();
- virtual ~mailbox();
-
- void drop_off(const structures::unique_int &id, letter *package);
- //!< drops a "package" in the mailbox for "id".
- /*!< note that when you send a package to someone, you give up all
- authority and control over that package. hopefully the end recipient
- will eventually pick it up and then delete it. if the package is never
- received, then this object will delete it. */
-
- bool pick_up(const structures::unique_int &id, letter * &package);
- //!< returns true if the mailbox for "id" had a "package" to be delivered.
- /*!< don't forget to check multiple times on a true outcome, since there
- could be more than one package waiting. false is returned when no more
- mail is waiting. be careful; "package" could be a bomb. dynamic casts
- seem appropriate as a method for ensuring that you get the type of
- object you expect. note that once the invoker receives a package, it
- is their responsibility to carefully manage it and then delete the
- package after handling. not deleting the "package" pointer is grounds
- for memory leaks. */
-
- int waiting(const structures::unique_int &id) const;
- //!< returns the number of items waiting for the "id" specified, if any.
-
- void get_ids(structures::int_set &to_fill);
- //!< stuffs the set "to_fill" with the ids of all mailboxes present.
- /*!< if you want only those mailboxes holding one or more letters, then
- call the clean_up() method prior to this method. */
-
- bool close_out(const structures::unique_int &id);
- //!< dumps all packages stored for the "id" and shuts down its mailbox.
- /*!< the destructors for those packages should never try to do anything
- with the mailbox system or a deadlock could result. true is returned if
- the "id" had a registered mailbox; false just indicates there was no box
- to clear up. */
-
- void show(basis::astring &to_fill);
- //!< provides a picture of what's waiting in the mailbox.
- /*!< this relies on the derived letter's required text_form() function. */
-
- void clean_up();
- //!< removes any empty mailboxes from our list.
-
- void limit_boxes(int max_letters);
- //!< establishes a limit on the number of letters.
- /*!< this is a helper function for a very special mailbox; it has a
- limited maximum size and any letters above the "max_letters" count will
- be deleted. don't use this function on any mailbox where all letters
- are important; your mailbox must have a notion of unreliability before
- this would ever be appropriate. */
-
- enum apply_outcomes {
- OKAY = basis::common::OKAY, //!< continue apply process.
-
- DEFINE_OUTCOME(APPLY_STOP, -46, "Halt the apply process"),
- DEFINE_OUTCOME(APPLY_WHACK, -47, "Removes the current letter, but "
- "continues"),
- DEFINE_OUTCOME(APPLY_WHACK_STOP, -48, "Halts apply and trashes the "
- "current letter")
- };
-
- typedef basis::outcome apply_function(letter ¤t, int uid, void *data_link);
- //!< the "apply_function" is what a user of apply() must provide.
- /*!< the function will be called on every letter in the mailbox unless one
- of the invocations returns APPLY_STOP or APPLY_WHACK_STOP; this causes
- the apply process to stop (and zap the node for APPLY_WHACK). the "uid"
- is the target for the "current" letter. the "data_link" provides a way
- for the function to refer back to a parent class or data package of some
- sort. note that all sorts of deadlocks will occur if your apply
- function tries to do anything on the mailbox, even transitively. keep
- those functions as simple as possible. */
-
- void apply(apply_function *to_apply, void *data_link);
- //!< calls the "to_apply" function on possibly every letter in the mailbox.
- /*!< this iterates until the function returns a 'STOP' outcome. the
- "data_link" pointer is passed to the apply function. NOTE: it is NOT safe
- to rearrange or manipulate the mailbox in any way from your "to_apply"
- function; the only changes allowed are those caused by the return value
- from "to_apply". */
-
-private:
- basis::mutex *_transaction_lock; //!< keeps the state of the mailbox safe.
- mailbox_bank *_packages; //!< the collection of mail that has arrived.
-
- // prohibited.
- mailbox(const mailbox &);
- mailbox &operator =(const mailbox &);
-};
-
-} //namespace.
-
-#endif
-
projects / feisty_meow.git / blobdiff