1 #ifndef ENTITY_DATA_BIN_CLASS
2 #define ENTITY_DATA_BIN_CLASS
4 /*****************************************************************************\
6 * Name : entity_data_bin *
7 * Author : Chris Koeritz *
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 \*****************************************************************************/
18 #include <basis/contracts.h>
19 #include <basis/definitions.h>
20 #include <basis/mutex.h>
21 #include <structures/set.h>
28 class entity_item_hash;
32 class octopus_request_id;
34 //! Stores a set of infotons grouped by the entity that owns them.
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. */
43 virtual ~entity_data_bin();
45 DEFINE_CLASS_NAME("entity_data_bin");
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.
56 // returns the number of entities that currently possess storage bins.
57 // this is a very costly call.
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.
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.
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.
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.
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.
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.
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.
99 basis::astring text_form() const;
100 // returns a textual list of what's held here.
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.
108 entity_item_hash *_table; // our main storage object.
109 basis::mutex *_ent_lock; // protects our structures.
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.
116 friend class monk_the_detective; // eerie supernatural powers, for testing.
118 int scramble_counter(); // counts the number of items used.
121 entity_data_bin(const entity_data_bin &);
122 entity_data_bin &operator =(const entity_data_bin &);