entity_data_bin.h

Go to the documentation of this file.

#ifndef ENTITY_DATA_BIN_CLASS
#define ENTITY_DATA_BIN_CLASS
 
/*****************************************************************************\
*                                                                             *
*  Name   : entity_data_bin                                                   *
*  Author : Chris Koeritz                                                     *
*                                                                             *
*******************************************************************************
* Copyright (c) 2002-$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/contracts.h>
#include <basis/definitions.h>
#include <basis/mutex.h>
#include <structures/set.h>
 
// forward.
class monk_the_detective;
 
namespace octopi {
 
// forward.
class basketcase;
class entity_basket;
class entity_item_hash;
class infoton;
class infoton_list;
class octopus_entity;
class octopus_request_id;
 
 
class entity_data_bin
{
public:
  entity_data_bin(int max_bytes_per_entity);
 
  virtual ~entity_data_bin();
 
  DEFINE_CLASS_NAME("entity_data_bin");
 
  int max_bytes_per_entity() const { return _max_per_ent; }
    // reports the maximum size allowed per entity for storage.
  void max_bytes_per_entity(int max_bytes_per) { _max_per_ent = max_bytes_per; }
    // allows resetting of the storage size allowed per entity.  note that if
    // this value is made smaller and the bin is already holding more than
    // the new limit, then no additional stores will be allowed until some of
    // the data is removed.
 
  int entities() const;
    // returns the number of entities that currently possess storage bins.
    // this is a very costly call.
 
  int items_held() const { return _items_held; }
    // returns the number of items held here, if any.  this is a very
    // inexpensive call that should be used prior to checking for data.
    // it's safe to check this at any time, since it's just an int.  there's
    // every likelihood that the number might change by the time one acquires
    // the lock on the bin, but if it's zero then that's a good reason to
    // avoid looking for data yet.
 
  bool get_sizes(const octopus_entity &id, int &items, int &bytes) const;
    // finds the storage for "id".  if there is any there, true is returned
    // and "items" is set to the number of pending items and "bytes" is set
    // to the number of bytes for those items.
 
  bool add_item(infoton *to_add, const octopus_request_id &id);
    // stores an item "to_add" for an entity listed in "id".  if the item
    // cannot be stored due to space constraints, false is returned and
    // "to_add" is deleted.
 
  infoton *acquire_for_identifier(const octopus_request_id &id);
    // locates an item for the specific "id".  this will generally be a
    // response to a previous request.  if no object can be found that matches
    // the "id", then NULL_POINTER is returned.
 
  infoton *acquire_for_entity(const octopus_entity &requester,
          octopus_request_id &id);
    // this returns an infoton for the "requester", if any are available.  call
    // this function repeatedly to ensure that all available items have
    // been provided.  the "original_id" is a copy of the "item_id" that was
    // originally passed to evaluate_request().  the returned object must
    // eventually be destroyed if non-null.
 
  int acquire_for_entity(const octopus_entity &requester,
          infoton_list &items, int maximum_size);
    // retrieves up to "maximum_size" in bytes of pending items for the
    // "requester" into "items".  the number of items found is returned.
 
  infoton *acquire_for_any(octopus_request_id &id);
    // acquires an infoton for any random entity.  if no items are ready at
    // all, then NULL_POINTER is returned.
 
  basis::astring text_form() const;
    // returns a textual list of what's held here.
 
  void clean_out_deadwood(int decay_interval = 4 * basis::MINUTE_ms);
    // gets rid of any items that haven't been picked up in a timely manner.
    // note that this should be called periodically by the controlling object.
    // it will not be called automatically.
 
private:
  entity_item_hash *_table;  // our main storage object.
  basis::mutex *_ent_lock;  // protects our structures.
  int _action_count;
    // used for debugging; tracks how many acquires have occurred since the
    // last dump of item count.
  int _max_per_ent;  // the maximum size allowed per entity.
  int _items_held;  // the number of items in residence.
 
  friend class ::monk_the_detective;  // eerie supernatural powers, for testing.
 
  basis::base_synchronizer &locker() { return *_ent_lock; }
 
  int scramble_counter();  // counts the number of items used.
 
  // not available.
  entity_data_bin(const entity_data_bin &);
  entity_data_bin &operator =(const entity_data_bin &);
};
 
} //namespace.
 
#endif