octopi/library/octopus/entity_data_bin.h

   1 #ifndef ENTITY_DATA_BIN_CLASS
   2 #define ENTITY_DATA_BIN_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : entity_data_bin                                                   *
   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 <basis/contracts.h>
  19 #include <basis/definitions.h>
  20 #include <basis/mutex.h>
  21 #include <structures/set.h>
  22
  23 namespace octopi {
  24
  25 // forward.
  26 class basketcase;
  27 class entity_basket;
  28 class entity_item_hash;
  29 class infoton;
  30 class infoton_list;
  31 class octopus_entity;
  32 class octopus_request_id;
  33
  34 //! Stores a set of infotons grouped by the entity that owns them.
  35
  36 class entity_data_bin
  37 {
  38 public:
  39   entity_data_bin(int max_bytes_per_entity);
  40     //!< allows each entity in the bin to have "max_bytes_per_entity" bytes stored.
  41     /*!<  any storage attempts that would go beyond that limit are rejected. */
  42
  43   virtual ~entity_data_bin();
  44
  45   DEFINE_CLASS_NAME("entity_data_bin");
  46
  47   int max_bytes_per_entity() const { return _max_per_ent; }
  48     // reports the maximum size allowed per entity for storage.
  49   void max_bytes_per_entity(int max_bytes_per) { _max_per_ent = max_bytes_per; }
  50     // allows resetting of the storage size allowed per entity.  note that if
  51     // this value is made smaller and the bin is already holding more than
  52     // the new limit, then no additional stores will be allowed until some of
  53     // the data is removed.
  54
  55   int entities() const;
  56     // returns the number of entities that currently possess storage bins.
  57     // this is a very costly call.
  58
  59   int items_held() const { return _items_held; }
  60     // returns the number of items held here, if any.  this is a very
  61     // inexpensive call that should be used prior to checking for data.
  62     // it's safe to check this at any time, since it's just an int.  there's
  63     // every likelihood that the number might change by the time one acquires
  64     // the lock on the bin, but if it's zero then that's a good reason to
  65     // avoid looking for data yet.
  66
  67   bool get_sizes(const octopus_entity &id, int &items, int &bytes);
  68     // finds the storage for "id".  if there is any there, true is returned
  69     // and "items" is set to the number of pending items and "bytes" is set
  70     // to the number of bytes for those items.
  71
  72   bool add_item(infoton *to_add, const octopus_request_id &id);
  73     // stores an item "to_add" for an entity listed in "id".  if the item
  74     // cannot be stored due to space constraints, false is returned and
  75     // "to_add" is deleted.
  76
  77   infoton *acquire_for_identifier(const octopus_request_id &id);
  78     // locates an item for the specific "id".  this will generally be a
  79     // response to a previous request.  if no object can be found that matches
  80     // the "id", then NIL is returned.
  81
  82   infoton *acquire_for_entity(const octopus_entity &requester,
  83           octopus_request_id &id);
  84     // this returns an infoton for the "requester", if any are available.  call
  85     // this function repeatedly to ensure that all available items have
  86     // been provided.  the "original_id" is a copy of the "item_id" that was
  87     // originally passed to evaluate_request().  the returned object must
  88     // eventually be destroyed if non-NIL.
  89
  90   int acquire_for_entity(const octopus_entity &requester,
  91           infoton_list &items, int maximum_size);
  92     // retrieves up to "maximum_size" in bytes of pending items for the
  93     // "requester" into "items".  the number of items found is returned.
  94
  95   infoton *acquire_for_any(octopus_request_id &id);
  96     // acquires an infoton for any random entity.  if no items are ready at
  97     // all, then NIL is returned.
  98
  99   basis::astring text_form() const;
 100     // returns a textual list of what's held here.
 101
 102   void clean_out_deadwood(int decay_interval = 4 * basis::MINUTE_ms);
 103     // gets rid of any items that haven't been picked up in a timely manner.
 104     // note that this should be called periodically by the controlling object.
 105     // it will not be called automatically.
 106
 107 private:
 108   entity_item_hash *_table;  // our main storage object.
 109   basis::mutex *_ent_lock;  // protects our structures.
 110   int _action_count;
 111     // used for debugging; tracks how many acquires have occurred since the
 112     // last dump of item count.
 113   int _max_per_ent;  // the maximum size allowed per entity.
 114   int _items_held;  // the number of items in residence.
 115
 116   friend class monk_the_detective;  // eerie supernatural powers, for testing.
 117
 118   int scramble_counter();  // counts the number of items used.
 119
 120   // not available.
 121   entity_data_bin(const entity_data_bin &);
 122   entity_data_bin &operator =(const entity_data_bin &);
 123 };
 124
 125 } //namespace.
 126
 127 #endif
 128