octopi/library/synchronic/list_manager.h

   1 #ifndef LIST_MANAGER_CLASS
   2 #define LIST_MANAGER_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : list_manager                                                      *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2002-$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 <octopus/tentacle.h>
  19
  20 namespace synchronic {
  21
  22 // forward.
  23 class synchronizable;
  24 class bundle_list;
  25
  26 //! Supports distributed management of a list of object states.
  27 /*!
  28   An object may have a collection of attributes which are important to keep
  29   up to date.  The list_manager provides a means to keep that information
  30   relevant given periodic updates to the state information by the entity in
  31   charge of the actual object.
  32 */
  33
  34 class list_manager : public octopi::tentacle
  35 {
  36 public:
  37   list_manager(const structures::string_array &list_name, bool backgrounded);
  38     // given the root of the "list_name", this will administrate the list.
  39     // all entries in the list must have "list_name" as their prefix.
  40     // if "backgrounded" is true, then this list will consume its requests
  41     // on a thread.  otherwise it deals with them immediately.
  42
  43   virtual ~list_manager();
  44
  45   int entries() const;  // returns the number of items held here.
  46
  47   const structures::string_array &list_name() const;
  48     // returns the list name this was constructed with (which is the same
  49     // as the group for this object).
  50
  51   bool is_listed(const structures::string_array &classifier);
  52     // returns true if the object with "classifier" exists in the list.
  53
  54   bool update(const structures::string_array &classifier, int offset = 0);
  55     // returns true if the object with "classifier" could be found and its
  56     // last update timestamp set to the current time if "offset" is zero.
  57     // if "offset" is negative, then the time will be updated to some time
  58     // before now.  if positive, then it's updated to a time after now.
  59
  60   void clean(int older_than);
  61     // flushes out any items that haven't been updated in "older_than"
  62     // microseconds.
  63
  64   synchronizable *clone_object(const structures::string_array &classifier);
  65     // returns a clone of the object listed for "classifier" or NIL if there
  66     // are none matching.  the returned object must be destroyed if non-NIL.
  67
  68   bool zap(const structures::string_array &classifier);
  69     // returns true if we were able to find and remove the item held under
  70     // the "classifier".
  71
  72   void retrieve(bundle_list &to_fill) const;
  73     // loads "to_fill" with a copy of the current set of attribute bundles.
  74
  75   void reset();
  76     // wipes out all objects that used to be listed.
  77
  78   virtual basis::outcome consume(octopi::infoton &to_chow,
  79           const octopi::octopus_request_id &item_id,
  80           basis::byte_array &transformed);
  81     // processes a request encapsulated in "to_chow".  the "item_id" is
  82     // currently unused.
  83
  84   virtual basis::outcome reconstitute(const structures::string_array &classifier,
  85           basis::byte_array &packed_form, octopi::infoton * &reformed) = 0;
  86     // recovers the original form "reformed" from a "packed_form" of the
  87     // object.  this must be provided by derived list_manager objects.
  88
  89   virtual void expunge(const octopi::octopus_entity &to_remove);
  90     // cleans out any items held for the entity "to_remove".
  91
  92 private:
  93   bundle_list *_entries;  // the set of elements that make up our list.
  94   basis::mutex *_locking;  // protects our contents.
  95
  96   int locked_find(const structures::string_array &classifier);
  97     // locates the item with the "classifier" in this list.  if it's present,
  98     // a non-negative index number is returned.
  99 };
 100
 101 } //namespace.
 102
 103 #endif
 104