core/library/processes/post_office.h

   1 #ifndef CENTRAL_MAILBOX_CLASS
   2 #define CENTRAL_MAILBOX_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : post_office                                                       *
   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 "mail_stop.h"
  19
  20 #include <processes/ethread.h>
  21 #include <timely/time_stamp.h>
  22
  23 namespace processes {
  24
  25 class letter;
  26 class letter_morph;
  27 class mailbox;
  28 class postal_cache;
  29 class route_map;
  30 class thread_cabinet;
  31
  32 //! Manages a collection of mailboxes and implements delivery routes for mail.
  33
  34 class post_office
  35 {
  36 public:
  37   post_office();
  38
  39   virtual ~post_office();
  40     //!< stop_serving must be invoked prior to this destructor.
  41
  42   void stop_serving();
  43     //!< gets the mailbox to stop delivering items prior to a shutdown.
  44
  45   // informational functions...
  46
  47   DEFINE_CLASS_NAME("post_office");
  48
  49   void show_mail(basis::astring &to_fill);
  50     //!< prints a snapshot of all currently pending letters into "to_fill".
  51
  52   void show_routes(basis::astring &to_fill);
  53     //!< writes a listing of the current routes into "to_fill".
  54
  55   // general delivery services subject to the constraints of the mailbox class.
  56
  57   void drop_off(const structures::unique_int &id, letter *package);
  58     //!< sends a "package" on its way to the "id" via the registered route.
  59     /*!< note that mail is not rejected if there is no known route to the
  60     mail_stop for the "id"; it is assumed in that case that the recipient
  61     will check at the post office. */
  62
  63   bool pick_up(const structures::unique_int &id, letter * &package);
  64     //!< retrieves a "package" intended for the "id" if one exists.
  65     /*!< false is returned if none are available.  on success, the "package" is
  66     filled in with the address of the package and it is the caller's
  67     responsibility to destroy or recycle() it after dealing with it. */
  68
  69   //////////////
  70
  71   // mail delivery and routing support.
  72
  73   bool register_route(const structures::unique_int &id, mail_stop &carrier_path);
  74     //!< registers a route "carrier_path" for mail deliveries to the "id".
  75
  76   bool unregister_route(const structures::unique_int &id);
  77     //!< removes a route for the "id".
  78     /*!< this should be done before the object's destructor is invoked since
  79     the letter carrier could be on his way with a letter at an arbitrary time.
  80     also, the mail_stop should be shut down (with end_availability()) at that
  81     time also.  if those steps are taken, then the carrier is guaranteed not
  82     to bother the recipient. */
  83
  84   bool route_listed(const structures::unique_int &id);
  85     //!< returns true if there is a route listed for the "id".
  86     /*!< this could change at any moment, since another place in the source
  87     code could remove the route just after this call.  it is information from
  88     the past by the time it's returned. */
  89
  90   //////////////
  91
  92   bool deliver_mail_on_route(const structures::unique_int &route, ethread &carrier);
  93     //!< for internal use only--delivers the letters to known routes.
  94     /*!< this function should only be used internally to prompt the delivery
  95     of packages that are waiting for objects we have a route to.  it returns
  96     true when all items that were waiting have been sent. */
  97
  98 private:
  99   basis::mutex c_mutt;  //!< protects our lists and dead letter office from corruption.
 100   mailbox *_post;  //!< the items awaiting handling.
 101   route_map *_routes;  //!< the pathways that have been defined.
 102   timely::time_stamp *_next_cleaning;  //!< when the next mailbox flush will occur.
 103   thread_cabinet *_threads;  //!< our list of threads for postal routes.
 104
 105   void get_route_list(structures::int_set &route_set);
 106     //!< retrieves the list of routes that we have registered.
 107
 108   void clean_package_list(post_office &post, letter_morph &to_clean);
 109     //!< recycles all of the letters held in "to_clean".
 110 };
 111
 112 } //namespace.
 113
 114 #endif
 115