deep mods
[feisty_meow.git] / octopi / library / octopus / octopus.h
1 #ifndef OCTOPUS_CLASS
2 #define OCTOPUS_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : octopus                                                           *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             *
9 *******************************************************************************
10 * Copyright (c) 2001-$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 <mathematics/chaos.h>
20 #include <processes/safe_roller.h>
21 #include <structures/set.h>
22 #include <timely/time_stamp.h>
23
24 namespace octopi {
25
26 // forward.
27 class entity_data_bin;
28 class filter_list;
29 class infoton;
30 class modula_oblongata;
31 class octopus_entity;
32 class octopus_request_id;
33 class tentacle;
34
35 //! Octopus is a design pattern for generalized request processing systems.
36 /*!
37   Octopus is a plug-in module manager that can serve as the base for highly
38   extensible program architectures.  Each module is called a tentacle,
39   following the conceit of the naming conventions, and it services one type
40   of request.  The requests come in the form of infoton objects, where the
41   tentacle that handles each class of infotons is uniquely identifiable.
42   Note that the outcomes returned here are from the tentacle's set of
43   outcomes.
44 */
45
46 class octopus : public virtual basis::root_object
47 {
48 public:
49   octopus(const basis::astring &name, int max_size_per_entity);
50     //!< constructs an octopus named "name".
51     /*!< the "name" string identifies the arena where this octopus is running.
52     this could be a network host or other identification string.  the
53     "max_size_per_entity" is the largest that we allow one entity's bin of
54     pending data to be.  this should be quite large if massive transactions
55     need to be processed. */
56
57   virtual ~octopus();
58
59   DEFINE_CLASS_NAME("octopus");
60
61   const basis::astring &name() const;
62     //!< returns the name that the octopus was constructed with.
63
64   // tentacle management functions...
65
66   basis::outcome add_tentacle(tentacle *to_add, bool filter = false);
67     //!< hooks a tentacle in to provide processing of one type of infoton.
68     /*!< lists the tentacle "to_add" as being responsible for handling requests
69     for the tentacle's group().  note that the octopus takes over control of
70     the "to_add" pointer; do not destroy that pointer independently, and do
71     not use the tentacle after adding it to the octopus unless the tentacle is
72     thread-safe.  the add will replace an existing tentacle if it was already
73     registered under the same group name.  if the "filter" flag is enabled,
74     then this tentacle is considered a filter; it will be consulted on all
75     infotons before they are processed.  filters will be invoked in the order
76     that they are added. */
77
78   basis::outcome remove_tentacle(const structures::string_array &group_name, tentacle * &free_me);
79     //!< removes the tentacle listed for the "group_name", if any.
80     /*!< "free_me" provides the means for getting back what was originally
81     registered.  NOTE: remember to destroy "free_me" if that's appropriate
82     (i.e. it was dynamically allocated, has no other users and no other entity
83     has responsibility for it). */
84
85   basis::outcome zap_tentacle(const structures::string_array &group_name);
86     //!< similar to remove_tentacle(), but destroys the tentacle.
87
88   // entity management methods...
89
90   octopus_entity issue_identity();
91     //!< creates an entity identifier that is unique for this octopus.
92     /*!< this provides a unique identity using the "name" specified in the
93     constructor and the current process id.  the sequence number and random
94     add_in are generated by this class also. */
95
96   void expunge(const octopus_entity &to_remove);
97     //!< invokes every tentacle's expunge() method on the id "to_remove".
98     /*!< this indicates that the entity is no longer extant and resources
99     held for it can be destroyed. */
100
101   entity_data_bin &responses();
102     //!< allows external access to our set of results.
103     /*!< this should not be used unless you know what you're doing. */
104
105   // main functionality: restoring infotons, evaluating requests and
106   // locating responses.
107
108   basis::outcome restore(const structures::string_array &classifier, basis::byte_array &packed_form,
109           infoton * &reformed);
110     //!< regenerates a packed infoton given its classifier.
111     /*!< locates the appropriate type of infoton with the "classifier" and
112     consumes the bytes in "packed_form" to return a new version of the original
113     data in "reformed", if possible. */
114
115   basis::outcome evaluate(infoton *request, const octopus_request_id &item_id,
116           bool now = false);
117     //!< tries to process the "request" using the current set of tentacles.
118     /*!< if there is no group handler for the "request", then NO_HANDLER will
119     be returned.  the classifier for "request" specifies the group name for
120     processing.  NOTE: the octopus assumes all responsibility for the
121     "request", even if the outcome denotes failure; do not touch the "request"
122     after this call.  if the "request" will be processed further by lower
123     level octopi, then the classifier can be patched as appropriate.  the
124     "item_id" must be maintained with the request in order to identify the
125     entity making the request and the sequence number of this particular
126     request.  the "now" parameter specifies whether the processing must occur
127     immediately; if false, the processing will occur later when the tentacle
128     get around to it.  if "now" is true, there is more load on the octopus
129     itself.  note that "now" is ignored if the tentacle does not support
130     backgrounding; true is always assumed for that case. */
131
132   infoton *acquire_result(const octopus_entity &requester,
133           octopus_request_id &original_id);
134     //!< acquires responses to previous requests if there are any waiting.
135     /*!< it returns an infoton for the "requester", if any are available.
136     call this function repeatedly to ensure that all responses have been
137     provided.  the "original_id" is a copy of the "item_id" that was
138     originally passed to evaluate_request().  the returned object must
139     eventually be destroyed if non-null. */
140
141   infoton *acquire_specific_result(const octopus_request_id &original_id);
142     //!< supports seeking the result for a specific request.
143     /*!< either the infoton that is a response to "original_id" will be
144     returned or NULL_POINTER. */
145
146   //////////////
147
148   // tentacle accessors: careful with these--you must always unlock after
149   // you have locked.
150
151   tentacle *lock_tentacle(const structures::string_array &tentacle_name);
152     //!< locates the tentacle with the "tentacle_name" and returns it.
153     /*!< the octopus will stay locked until the unlock_tentacle() method is
154     invoked. */
155
156   void unlock_tentacle(tentacle *to_unlock);
157     //!< unlocks the octopus when given a previously locked tentacle.
158     /*!< this must be the same object that was obtained via the
159     lock_tentacle() method. */
160
161   void lock_tentacles();
162     //!< locks the tentacle list for use with locked_get_tentacle.
163
164   // the following are only valid if the tentacle list is locked.
165   int locked_tentacle_count();  //!< number of tentacles.
166   tentacle *locked_get_tentacle(int indy);  //!< access indy'th tentacle.
167   void unlock_tentacles();  //!< unlocks the list.
168
169   //////////////
170
171   // used internally; don't mess with externally.
172
173   void periodic_cleaning();
174     //!< flushes any abandoned data from the response bin.
175
176 private:
177   basis::astring *_name;  //!< our name as passed to the constructor.
178   modula_oblongata *_tentacles;  //!< the list of tentacles.  
179   basis::mutex *_molock;  //!< the synchronizer for our tentacle list.
180   entity_data_bin *_responses;  //!< data awaiting pickup by requester.
181   int _disallow_removals;
182     //!< simplifies locking behavior for immediate requests.
183     /*!< we set this flag and don't need to lock the whole octopus.  if it's
184     non-zero, then no tentacles can be removed yet. */
185   timely::time_stamp *_next_cleaning;  //!< when we'll next flush old items.
186   basis::mutex *_clean_lock;  //!< used only to protect the time stamp above.
187   filter_list *_filters;  //!< the filters that must vet infotons.
188   processes::safe_roller *_sequencer;  //!< identity issue; this is the next entity id.
189   mathematics::chaos *_rando;  //!< randomizer for providing extra uniquification.
190
191   // not accessible.
192   octopus(const octopus &);
193   octopus &operator =(const octopus &);
194 };
195
196 } //namespace.
197
198 #endif
199