Merge branch 'master' of feistymeow.org:feisty_meow
[feisty_meow.git] / octopi / library / octopus / entity_defs.h
1 #ifndef ENTITY_DEFINITIONS_GROUP
2 #define ENTITY_DEFINITIONS_GROUP
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : various definitions for octopus                                   *
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 "infoton.h"
19
20 #include <basis/byte_array.h>
21 #include <basis/astring.h>
22 #include <structures/set.h>
23 #include <structures/amorph.h>
24 #include <structures/unique_id.h>
25 #include <timely/time_stamp.h>
26
27 namespace octopi {
28
29 //! Provides a way of identifying users of an octopus object.
30 /*!
31   NOTE: this is a heavy-weight header intended for forward declaration.
32 */
33
34 class octopus_entity : public virtual basis::packable, public virtual basis::text_formable
35 {
36 public:
37   octopus_entity();  //!< blank constructor.
38
39   octopus_entity(const basis::astring &hostname, int process_id, int sequencer,
40           int add_in);
41     //!< constructor taking all the available parameters for an entity.
42     /*!< produces an id in the proper format given all the components.  note
43     that the hostname must be some fully qualified name for the host, such
44     that it is as unique as you want names within the system to be. */
45
46   octopus_entity(const octopus_entity &to_copy);
47
48   ~octopus_entity();
49
50   octopus_entity &operator = (const octopus_entity &to_copy);
51
52   DEFINE_CLASS_NAME("octopus_entity");
53
54   bool blank() const;
55     //!< true if the entity is blank, as constructed by default constructor.
56
57   // comparison operators.
58   bool operator == (const octopus_entity &that) const;
59
60   const basis::astring &hostname() const;  //!< returns the hostname portion of the id.
61   int process_id() const;   //!< returns the process number in the id.
62   int sequencer() const;    //!< returns the sequencing number from the id.
63   int add_in() const;       //!< returns the random add-in from the id.
64
65   void hostname(const basis::astring &new_host);  //!< set the host.
66   void process_id(int id);  //!< set the process id.
67   void sequencer(int seq);  //!< set the sequencer value.
68   void add_in(int add);  //!< set the add-in value.
69
70   basis::astring mangled_form() const;
71     //!< returns the combined string form of the identifier.
72
73   basis::astring text_form() const;
74     //!< returns a readable form of the identifier.
75
76   virtual void text_form(basis::base_string &to_fill) const {
77     to_fill.assign(text_form());
78   }
79
80   basis::astring to_text() const { return mangled_form(); }
81     //!< conversion to text format for display.
82   static octopus_entity from_text(const basis::astring &to_convert);
83     //!< conversion from text format, parsing parameters out.
84
85   static void breakout(const basis::astring &mangled_form, basis::astring &hostname,
86           int &process_id, int &sequencer, int &add_in);
87     //!< takes a "mangled_form" of an entity id and retrieves the components.
88
89   int packed_size() const;
90     //!< reports how large the packed entity will be.
91
92   virtual void pack(basis::byte_array &packed_form) const;
93   virtual bool unpack(basis::byte_array &packed_form);
94
95 private:
96   basis::astring *_hostname;
97   int _pid;
98   int _sequencer;
99   int _add_in;
100 };
101
102 //////////////
103
104 //! Identifies requests made on an octopus by users.
105 /*!
106   Uniquely identifies a request passed to an octopus server given that
107   the number of requests from one entity can be contained within the range
108   of signed integers.  if the requests come fast enough for the request
109   numbers to wrap around, and if the requests can remain outstanding for a
110   really long time, it may be wise to create a new login.
111 */
112
113 class octopus_request_id : public virtual basis::packable
114 {
115 public:
116   octopus_entity _entity;  //!< the entity.
117   int _request_num;  //!< the item number from the entity.
118
119   octopus_request_id() : _entity(), _request_num(0) {}
120
121   octopus_request_id(const octopus_entity &entity, int request_num)
122       : _entity(entity), _request_num(request_num) {}
123
124   static octopus_request_id randomized_id();
125     //!< provides a pre-randomized request id.
126     /*!< this should only be used for the very first request made to an
127     octopus, in order to obtain a valid identity. */
128
129   bool operator == (const octopus_request_id &that) const
130           { return (_entity == that._entity)
131                 && (_request_num == that._request_num); }
132
133   bool blank() const;
134     //!< returns true if this is a blank id (as constructed by default ctor).
135
136   int packed_size() const;
137     //!< reports how large the packed id will be.
138
139   basis::astring mangled_form() const;  //!< similar to entity id.
140   
141   basis::astring text_form() const;  //!< human readable form of the request.
142
143   basis::astring to_text() const { return mangled_form(); }
144   static octopus_request_id from_text(const basis::astring &to_convert);
145
146   virtual void pack(basis::byte_array &packed_form) const;
147   virtual bool unpack(basis::byte_array &packed_form);
148 };
149
150 //! a collection of unique request ids.
151 class octopus_request_id_set : public structures::set<octopus_request_id>
152 {
153 public:
154   octopus_request_id_set() {}
155
156   octopus_request_id_set(const structures::set<octopus_request_id> &orig)
157       : structures::set<octopus_request_id>(orig) {}
158 };
159
160 //////////////
161
162 //! implements a list of waiting infotons.
163 /*! the actual infoton plus its request id are stored. */
164
165 class infoton_id_pair : public virtual basis::root_object
166 {
167 public:
168   infoton *_data;
169   octopus_request_id _id;
170
171   infoton_id_pair(infoton *data, const octopus_request_id &id)
172       : _data(data), _id(id) {}
173
174   ~infoton_id_pair() {
175     delete _data;
176     _data = NULL_POINTER;
177   }
178 };
179
180 //! a list of pending requests and who made them.
181 class infoton_list : public structures::amorph<infoton_id_pair> {};
182
183 } //namespace.
184
185 #endif
186