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