casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ObjectID.h
Go to the documentation of this file.
1 //# ObjectID.h: A unique identifier for distributed and other objects
2 //# Copyright (C) 1996,1998,1999,2000,2001,2003
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 
29 #ifndef CASA_OBJECTID_H
30 #define CASA_OBJECTID_H
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
35 #include <casacore/casa/iosfwd.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward declarations
40 template<class T> class Block;
41 
42 // <summary>
43 // ObjectID: A unique identifier for distributed and other objects.
44 // </summary>
45 
46 // <use visibility=export>
47 
48 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tObjectID.cc" demos="">
49 
50 // <prerequisite>
51 // <li> none
52 // </prerequisite>
53 //
54 // <etymology>
55 // The ObjectID class name reflects its role as the single identifier for
56 // distributed and other user-level objects.
57 // </etymology>
58 //
59 // <synopsis>
60 // The ObjectID class is used to give a unique identifier to ``high-level''
61 // objects in the system. Internally the ObjectID consists of a sequence number
62 // (unique within the creating process), a process id, a creation time, and a
63 // host id. Pragmatically the ObjectID should be unique with no dangers of
64 // collisions.
65 //
66 // A special ``Null'' ObjectID is available.
67 // </synopsis>
68 //
69 // <motivation>
70 // The fundamental purpose for an ObjectID is to provide a unique identifier
71 // for persistent objects, or for objects that might be accessed outside the
72 // creating processes address space.
73 // </motivation>
74 //
75 // <todo asof="1997/09/23">
76 // <li> Nothing (hostid -> hostname on this date).
77 // </todo>
78 
79 class ObjectID
80 {
81 public:
82  // If <src>makeNull</src> is True, make the null ObjectID, otherwise create
83  // a unique ObjectID.
84  ObjectID(Bool makeNull = False);
85  // Create explicitly from the provided constituents.
86  ObjectID(Int sequence, Int pid, Int time, const String &hostname);
87 
88  // Copy <src>other</src>. Note that if the ObjectID is embedded inside an
89  // object, the enclosing object probably does not want to copy the ObjectID
90  // since generally speaking the identity of the enclosing object should be
91  // immutable.
92  // <group>
93  ObjectID(const ObjectID &other);
94  ObjectID &operator=(const ObjectID &other);
95  // </group>
96 
97  // Is this ObjectID set?
98  Bool isNull() const;
99 
100  // Compare two ObjectID's for (in)equality.
101  // <group>
102  Bool operator==(const ObjectID &other) const;
103  Bool operator!=(const ObjectID &other) const;
104  // </group>
105 
106  // It is useful to interconvert between strings and ObjecID's, e.g. when
107  // saving to FITS or writing to a table. The form of the string is:
108  // <srcblock>
109  // sequence=123 host=hostname pid=pid time=time
110  // </srcblock>
111  // with an optional comma between the fields.
112  // However, in general user code should not depend on the exact form of
113  // the string.
114  // <group>
115  // If this fails, an error message is set and the ObjectID is the null
116  // ObjectID.
117  Bool fromString(String &error, const String &in);
118  // Note that <src>out</src> is zero'd before it is set.
119  void toString(String &out) const;
120  // </group>
121 
122  // Ordinarily the user does not need to get at the exact state of the,
123  // ObjectID, however it is available for those times when it is necessary.
124  // <group>
125  Int sequence() const;
126  Int pid() const;
127  Int creationTime() const;
128  const String &hostName() const;
129  // </group>
130 
131  // Extract objectID strings (as set by glish script substitute.g) from
132  // a command, convert them to ObjectID objects, store those in the
133  // Block, and replace the strings by their Block indices as
134  // <src>$OBJ#n#O</src> where n is the index.
135  static String extractIDs (Block<ObjectID>& objectIDs,
136  const String& command);
137 
138 private:
143 
144  // Make a unique sequence number, returns 0 on first call, 1 on next, ...
145  static Int sequence_number();
146 };
147 
148 uInt hashFunc(const ObjectID &);
149 
150 ostream &operator<<(ostream &os, const ObjectID &id);
151 
152 //# Inlines
153 
154 inline Int ObjectID::sequence() const
155 {
156  return sequence_number_p;
157 }
158 
159 inline Int ObjectID::pid() const
160 {
161  return process_id_p;
162 }
163 
165 {
166  return creation_time_p;
167 }
168 
169 inline const String &ObjectID::hostName() const
170 {
171  return hostname_p;
172 }
173 
174 
175 } //# NAMESPACE CASACORE - END
176 
177 #endif
int Int
Definition: aipstype.h:50
TableExprNode time(const TableExprNode &node)
Definition: ExprNode.h:1537
ObjectID: A unique identifier for distributed and other objects.
Definition: ObjectID.h:79
Int creationTime() const
Definition: ObjectID.h:164
ostream & operator<<(ostream &os, const std::pair< T, U > &p)
Bool fromString(String &error, const String &in)
It is useful to interconvert between strings and ObjecID&#39;s, e.g.
Int sequence() const
Ordinarily the user does not need to get at the exact state of the, ObjectID, however it is available...
Definition: ObjectID.h:154
const String & hostName() const
Definition: ObjectID.h:169
ObjectID(Bool makeNull=False)
If makeNull is True, make the null ObjectID, otherwise create a unique ObjectID.
Bool operator==(const ObjectID &other) const
Compare two ObjectID&#39;s for (in)equality.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
uInt hashFunc(const ObjectID &)
const Bool False
Definition: aipstype.h:44
Bool operator!=(const ObjectID &other) const
static Int sequence_number()
Make a unique sequence number, returns 0 on first call, 1 on next,...
simple 1-D array
Bool isNull() const
Is this ObjectID set?
static String extractIDs(Block< ObjectID > &objectIDs, const String &command)
Extract objectID strings (as set by glish script substitute.g) from a command, convert them to Object...
void toString(String &out) const
Note that out is zero&#39;d before it is set.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
ObjectID & operator=(const ObjectID &other)
Int pid() const
Definition: ObjectID.h:159
unsigned int uInt
Definition: aipstype.h:51
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42