XRootD
XrdSsi::ShMap< T > Class Template Reference

#include <XrdSsiShMap.hh>

+ Collaboration diagram for XrdSsi::ShMap< T >:

Public Member Functions

 ShMap (const char *typeName, ShMap_Hash_t hFunc=0, const char *implName=0)
 
 ~ShMap ()
 Destructor. More...
 
bool Add (const char *key, T &val)
 
bool Attach (const char *path, ShMap_Access access, int tmo=-1)
 
bool Create (const char *path, ShMap_Parms &parms)
 
bool Del (const char *key, T *valP=0)
 
void Detach ()
 Detach the map from the shared memory. More...
 
bool Enumerate (void *&jar)
 
bool Enumerate (void *&jar, char *&key, T *&val)
 
bool Exists (const char *key)
 
bool Export ()
 
bool Get (const char *key, T &val)
 
int Info (const char *vname, char *buff=0, int blen=0)
 
bool Rep (const char *key, T &val, T *valP=0)
 
bool Resize (ShMap_Parms *parms=0)
 
bool Sync (SyncOpt dosync, int syncqsz=256)
 

Detailed Description

template<class T>
class XrdSsi::ShMap< T >

Definition at line 125 of file XrdSsiShMap.hh.

Constructor & Destructor Documentation

◆ ShMap()

template<class T >
XrdSsi::ShMap< T >::ShMap ( const char *  typeName,
ShMap_Hash_t  hFunc = 0,
const char *  implName = 0 
)
inline

Constructor. First allocate a ShMap object of appropriate type. Then call Attach() to attach it to a shared memory segment before calling any other method in this class. When through either delete the object.

Parameters
typeName- A text name of the type in the map. Attach() makes sure that the map has this type. Specify text < 64 characters. Example: XrdSsi::ShMap<int> myMap("int");
hFunc- An optional pointer to to the hash computation function to be used. If not specified, a crc32 hash is used.
implName- A text name of the map implementation desired. Zero uses the default implementation. Currently only the default implementation is available.

Definition at line 403 of file XrdSsiShMap.hh.

405  : shMat(0), hashFunc(hFunc), typeID(strdup(typeName)),
406  implID((implName ? strdup(implName) : 0)) {}

◆ ~ShMap()

template<class T >
XrdSsi::ShMap< T >::~ShMap ( )
inline

Destructor.

Definition at line 412 of file XrdSsiShMap.hh.

412  {Detach();
413  if (typeID) free(typeID);
414  if (implID) free(implID);
415  }
void Detach()
Detach the map from the shared memory.

References XrdSsi::ShMap< T >::Detach().

+ Here is the call graph for this function:

Member Function Documentation

◆ Add()

template<class T >
bool XrdSsi::ShMap< T >::Add ( const char *  key,
T &  val 
)

Add an item to the map (see the Rep() method for key/data replacement).

Parameters
keypointer to the key of length <= MaxKeySize.
valThe associated data to be added to the map.
Returns
true - The key and data added to the map.
false - The key and data not added, the errno value describes why. Typical reason: the key already exists (errno == EEXIST).

Definition at line 37 of file XrdSsiShMap.icc.

38 {
39 // Make sure we have memory
40 //
41  if (!shMat) {errno = ENOTCONN; return false;}
42 
43 // Compute hash if need be
44 //
45  int hash = (hashFunc ? hashFunc(key) : 0);
46 
47 // Rteurn the result
48 //
49  return shMat->AddItem(&val, 0, key, hash, false);
50 }
virtual bool AddItem(void *newdata, void *olddata, const char *key, int hash=0, bool replace=false)=0

◆ Attach()

template<class T >
bool XrdSsi::ShMap< T >::Attach ( const char *  path,
XrdSsi::ShMap_Access  access,
int  tmo = -1 
)

Attach an existing shared memory map.

Parameters
pathPointer to the file that is or will represent the map.
accessHow to attach the map. Specify one of the following: ReadOnly - Attach the map strictly for reading. ReadWrite - Attach the map in read/write mode. New and
tmoHow many seconds to wait for the map to appear. It is possible that a new map may have not yet been exported, so attach will wait for the map to become visible. Specify, <0 - wait forever. =0 - do not wait at all. >0 - wait the specified number seconds and then timeout.
Returns
true - The shared memory was attached, the map can be used.
false - The shared memory could not be attached, errno holds reason.

Definition at line 57 of file XrdSsiShMap.icc.

60 {
61  static const int waitSec = 2;
62  XrdSsiShMat::NewParms newParms;
63  int rc, tries= (tmo < 0 ? 120 : (tmo < 4 ? tmo : tmo/waitSec));
64  bool isRW = (access == XrdSsi::ReadOnly ? false : true);
65 
66 // First see if this object is already attached.
67 //
68  if (shMat) {errno = EISCONN; return false;}
69 
70 // Set the object attach parameters
71 //
72  newParms.impl = implID;
73  newParms.path = path;
74  newParms.typeID = typeID;
75  newParms.typeSz = sizeof(T);
76  newParms.hashID = (hashFunc ? hashFunc(0) : 0);
77 
78 // Allocate a new shared memory generic object
79 //
80  shMat = XrdSsiShMat::New(newParms);
81  if (!shMat) return false;
82 
83 // Handle the action. There is an edge case where we will need to try to attach
84 // the map again. We only do that for a limited number of times as this is a
85 // condition that should not occur for any long amount of time.
86 //
87  do {if (shMat->Attach(tmo, isRW)) return true;
88  if (errno != EAGAIN) break;
89  if (tries--) sleep(waitSec);
90  } while(tries > 0);
91  if (tries) errno = ECANCELED;
92 
93 // We failed
94 //
95  rc = errno;
96  delete shMat; shMat = 0;
97  errno = rc;
98  return false;
99 }
int access(const char *path, int amode)
const char * typeID
The name of the type associated with the key.
Definition: XrdSsiShMat.hh:279
const char * impl
Implementation name.
Definition: XrdSsiShMat.hh:277
static XrdSsiShMat * New(NewParms &parms)
Definition: XrdSsiShMat.cc:39
const char * path
The path to the backing file for the table.
Definition: XrdSsiShMat.hh:278
virtual bool Attach(int tout, bool isrw=false)=0
int hashID
The hash being used (0 means the default)
Definition: XrdSsiShMat.hh:281
int typeSz
Size of the type in bytes.
Definition: XrdSsiShMat.hh:280
@ ReadOnly
reading
Definition: XrdSsiShMap.hh:50

References access(), XrdSsiShMat::NewParms::hashID, XrdSsiShMat::NewParms::impl, XrdSsiShMat::New(), XrdSsiShMat::NewParms::path, XrdSsi::ReadOnly, XrdSsiShMat::NewParms::typeID, and XrdSsiShMat::NewParms::typeSz.

+ Here is the call graph for this function:

◆ Create()

template<class T >
bool XrdSsi::ShMap< T >::Create ( const char *  path,
XrdSsi::ShMap_Parms parms 
)

Create a new r/w shared memory map possibly replacing an existing one upon export. New maps must be exported to become visible (see Export()).

This method first creates a temporary map visible only to the creator. This allows you to fill the map as needed with minimal overhead. Once this is done, call Export() to make the new map visible, possibly replacing an any existing version of a map with the same name.

Parameters
pathPointer to the file that is or will represent the map.
parmsReference to the parameters. See the ShMap_Parms struct for for details and constructor defaults. Below is a detailed explanation of the available options:

MultW - The map has multiple processes writing to it. All writers must obtain an exclusive file lock before updating the map. No file locks are needed ReUse - Allow reuse of storage in the map. Use this if the map has many inserts/deletes. If set, r/o access will always lock the map file before looking at it. Otherwise, there is no need for file locks as no item is ever reused. ReUse is good when there are few key add/delete cycles.

Returns
true - The shared memory was attached, the map can be used.
false - The shared memory could not be attached, errno holds reason.

Definition at line 106 of file XrdSsiShMap.icc.

107 {
108  XrdSsiShMat::NewParms newParms;
109  XrdSsiShMat::CRZParms crzParms;
110  int rc;
111 
112 // First see if this object is already attached.
113 //
114  if (shMat) {errno = EISCONN; return false;}
115 
116 // Set the object creation parameters
117 //
118  newParms.impl = implID;
119  newParms.path = path;
120  newParms.typeID = typeID;
121  newParms.typeSz = sizeof(T);
122  newParms.hashID = (hashFunc ? hashFunc(0) : 0);
123 
124 // Allocate a new shared memory generic object
125 //
126  shMat = XrdSsiShMat::New(newParms);
127  if (!shMat) return false;
128 
129 // Copy over the create parameters
130 //
131  crzParms.indexSz = parms.indexSize;
132  crzParms.maxKeys = parms.maxKeys;
133  crzParms.maxKLen = parms.maxKeyLen;
134  crzParms.mode = parms.mode;
136  crzParms.reUse = (parms.options & ~XrdSsi::ShMap_Parms::noReUse ? 1 : 0);
138  crzParms.multW = (parms.options & ~XrdSsi::ShMap_Parms::noMultW ? 1 : 0);
139 
140 // Handle the action
141 //
142  if (shMat->Create(crzParms)) return true;
143 
144 // We failed
145 //
146  rc = errno;
147  delete shMat; shMat = 0;
148  errno = rc;
149  return false;
150 }
virtual bool Create(CRZParms &parms)=0
int maxKeys
Maximum number of keys-value pairs expected in table.
Definition: XrdSsiShMat.hh:101
int maxKLen
The maximum acceptable key length.
Definition: XrdSsiShMat.hh:102
int mode
Filemode for the newly created file.
Definition: XrdSsiShMat.hh:103
int indexSz
Number of four byte hash table entries to create.
Definition: XrdSsiShMat.hh:100
static const int MultW
Bit options that may be or'd into he options member above.
Definition: XrdSsiShMap.hh:75
int maxKeys
Maximum expected keys.
Definition: XrdSsiShMap.hh:65
int mode
Mode setting for the newly created file.
Definition: XrdSsiShMap.hh:66
int maxKeyLen
Maximum key length.
Definition: XrdSsiShMap.hh:64
static const int ReUse
Reuse map storage.
Definition: XrdSsiShMap.hh:79
int options
Bit or'd ShMop_xxxx options below.
Definition: XrdSsiShMap.hh:67
int indexSize
Number of hash table entries to create.
Definition: XrdSsiShMap.hh:63

References XrdSsiShMat::NewParms::hashID, XrdSsiShMat::NewParms::impl, XrdSsi::ShMap_Parms::indexSize, XrdSsiShMat::CRZParms::indexSz, XrdSsi::ShMap_Parms::maxKeyLen, XrdSsi::ShMap_Parms::maxKeys, XrdSsiShMat::CRZParms::maxKeys, XrdSsiShMat::CRZParms::maxKLen, XrdSsi::ShMap_Parms::mode, XrdSsiShMat::CRZParms::mode, XrdSsi::ShMap_Parms::MultW, XrdSsiShMat::CRZParms::multW, XrdSsiShMat::New(), XrdSsi::ShMap_Parms::options, XrdSsiShMat::NewParms::path, XrdSsi::ShMap_Parms::ReUse, XrdSsiShMat::CRZParms::reUse, XrdSsiShMat::NewParms::typeID, and XrdSsiShMat::NewParms::typeSz.

+ Here is the call graph for this function:

◆ Del()

template<class T >
bool XrdSsi::ShMap< T >::Del ( const char *  key,
T *  valP = 0 
)

Delete an item from the map.

Parameters
keyPointer to the key of length <= MaxKeySize.
valPPointer to the area to receive the value of the deleted key. If the pointer is nil, then the key value is not returned.
Returns
true - The key and data have been deleted. This is always returned when valP is nil.
false - The key and data either not deleted or the key does not exist and valP was not nil. The errno value describes why. Typical reason: the key was not found (errno == ENOENT).

Definition at line 157 of file XrdSsiShMap.icc.

158 {
159 // Make sure we have memory
160 //
161  if (!shMat) {errno = ENOTCONN; return false;}
162 
163 // Compute hash if need be
164 //
165  int hash = (hashFunc ? hashFunc(key) : 0);
166 
167 // Return the result
168 //
169  return shMat->DelItem(valP, key, hash);
170 }
virtual bool DelItem(void *data, const char *key, int hash=0)=0

◆ Detach()

template<class T >
void XrdSsi::ShMap< T >::Detach

Detach the map from the shared memory.

Definition at line 177 of file XrdSsiShMap.icc.

178 {
179 // If we have memory, detach it
180 //
181  if (shMat) {delete shMat; shMat = 0;}
182 }

Referenced by XrdSsi::ShMap< T >::~ShMap().

+ Here is the caller graph for this function:

◆ Enumerate() [1/2]

template<class T >
bool XrdSsi::ShMap< T >::Enumerate ( void *&  jar)

Terminate an active enumeration. An active enumeration is any enumeration where the previous form of Enumerate() did not return false. Terminating an active enumeration releases all of the enumeration resources allocated.

Parameters
jarThe opaque cookie initialized by a previous call to Enumerate() whose enumeration is to be terminated.
Returns
true The enumeration has been terminated and the jar was deleted and the jar pointer is set to zero. Keys are returned in arbitrary order and not all keys may be returned if the map is being actively updated.
false The jar pointer was zero; no enumeration was active.

Definition at line 203 of file XrdSsiShMap.icc.

204 {
205 // Make sure we have memory
206 //
207  if (!shMat) {errno = ENOTCONN; return false;}
208 
209 // Terminate the enumeration
210 //
211  return shMat->Enumerate(jar);
212 }
virtual bool Enumerate(void *&jar, char *&key, void *&val)=0

◆ Enumerate() [2/2]

template<class T >
bool XrdSsi::ShMap< T >::Enumerate ( void *&  jar,
char *&  key,
T *&  val 
)

Enumerate the keys and associated values.

Parameters
jarAn opaque cookie that tracks progress. It should be initialized to zero and otherwise not touched. The same jar must be used for all successive calls. The jar is deleted when false is returned (also see the next Enumerate method).
keyThe pointer variable where the location of the key is returned upon success. The key is overwritten on the next call to Enumerate(); so copy it if you want to keep it.
valThe pointer variable where the location of the key value is to be returned upon success. The value is overwritten on the next call to Enumerate(). Copy it if you want to keep it.
Returns
true A key and val pointers have been set. Keys are returned in arbitrary order and not all keys may be returned if the map is being actively updated.
false Key not returned; errno holds the reason. Typically, ENOENT there ae no more keys. Other errors may also be reflected. Whene false is returned the jar is deleted and the pointer to it set to zero.

Definition at line 189 of file XrdSsiShMap.icc.

190 {
191 // Make sure we have memory
192 //
193  if (!shMat) {errno = ENOTCONN; return false;}
194 
195 // Return next key and possibly an assocaited value
196 //
197  return shMat->Enumerate(jar, key, (void *&)val);
198 }

◆ Exists()

template<class T >
bool XrdSsi::ShMap< T >::Exists ( const char *  key)

Determine whether or not a key exists in the map.

Parameters
keyPointer to the key of length <= MaxKeySize.
Returns
true - The key exists.
false - The key does not exist.

Definition at line 219 of file XrdSsiShMap.icc.

220 {
221 // Make sure we have memory
222 //
223  if (!shMat) {errno = ENOTCONN; return false;}
224 
225 // Compute hash if need be
226 //
227  int hash = (hashFunc ? hashFunc(key) : 0);
228 
229 // Return the result
230 //
231  return shMat->GetItem(0, key, hash);
232 }
virtual bool GetItem(void *data, const char *key, int hash=0)=0

◆ Export()

template<class T >
bool XrdSsi::ShMap< T >::Export

Export a newly created map (i.e. one that was attached using ShMop_New).

Returns
true - The map has been exported and is now visible to others.
false - The export failed, the errno value describes the reason.

Definition at line 239 of file XrdSsiShMap.icc.

240 {
241 // Make sure we have memory
242 //
243  if (!shMat) {errno = ENOTCONN; return false;}
244 
245 // Return result
246 //
247  return shMat->Export();
248 }
virtual bool Export()=0

◆ Get()

template<class T >
bool XrdSsi::ShMap< T >::Get ( const char *  key,
T &  val 
)

Find a key in the map and return its value.

Parameters
keyPointer to the key of length <= MaxKeySize.
valReference to the area to receive the value of the found key.
Returns
true - The key found and its value has been returned.
false - The key not found, the errno value describes why. Typical reason: the key was not found (errno == ENOENT).

Definition at line 255 of file XrdSsiShMap.icc.

256 {
257 // Make sure we have memory
258 //
259  if (!shMat) {errno = ENOTCONN; return false;}
260 
261 // Compute hash if need be
262 //
263  int hash = (hashFunc ? hashFunc(key) : 0);
264 
265 // Return the result
266 //
267  return shMat->GetItem(&val, key, hash);
268 }

◆ Info()

template<class T >
int XrdSsi::ShMap< T >::Info ( const char *  vname,
char *  buff = 0,
int  blen = 0 
)

Return information about the map.

Parameters
vnamePointer to the variable name whose value is wanted. A particular implementation may not support all variable and may support variables not listed here. These are for the default implementation unless otherwise noted. They are: hash - name of hash being used. impl - The table implementation being used. indexsz - Number of index entries indexused - Number of index entries in use keys - Number of keys in the map. keys/indexused is the hash table collision factor keysfree - Number of keys that can still be added maxkeylen - Longest allowed key multw - If 1 map supports multiple writers, else 0 reuse - If 1 map allows object reuse, else 0 type - Name of the data type in the table. typesz - The number of bytes in the map's data type
buff- Pointer to the buffer to receive text values. Variables that return text are: hash, impl, and type. A buffer must be supplied in any of these variables are requested. If buff is nill or too small a -1 is returned with errno set to EMSGSIZE.
blenThe length of the buffer.
Returns
>=0 - The variable's value.
< 0 - The variable's value could not be returned; errno has the error code describing the reason, typically ENOTSUP.

Definition at line 275 of file XrdSsiShMap.icc.

276 {
277 // Make sure we have memory
278 //
279  if (!shMat) {errno = ENOTCONN; return -1;}
280 
281 // Return the result
282 //
283  return shMat->Info(vname, buff, blen);
284 }
virtual int Info(const char *vname, char *buff=0, int blen=0)=0

◆ Rep()

template<class T >
bool XrdSsi::ShMap< T >::Rep ( const char *  key,
T &  val,
T *  valP = 0 
)

Add to or replace an item in the map.

Parameters
keyPointer to the key of length <= MaxKeySize.
valThe associated data to be added to or replaced in the map.
valPPointer to the area to receive the value of a replaced key. If the pointer is nil, then the key value is not returned.
Returns
true - The key and data added to or replaced in the map. If the key was replaced errno is set to EEXIST else it is set to 0.
false - The key and data not added, the errno value describes why. Typical reason: the key was too long (errno == ENAMETOOLONG).

Definition at line 291 of file XrdSsiShMap.icc.

292 {
293 // Make sure we have memory
294 //
295  if (!shMat) {errno = ENOTCONN; return false;}
296 
297 // Compute hash if need be
298 //
299  int hash = (hashFunc ? hashFunc(key) : 0);
300 
301 // Rteurn the result
302 //
303  return shMat->AddItem(&val, valP, key, hash, true);
304 }

◆ Resize()

template<class T >
bool XrdSsi::ShMap< T >::Resize ( XrdSsi::ShMap_Parms parms = 0)

Resize or change options on an existing map attached in read/write mode. The map must have been exported.

Parameters
parmsPointer to the parameters. See the ShMap_Parms struct for for details and constructor defaults. A zero value in the parameter list uses the existing map value allowing you to selectively change the map sizing and options. If a nil pointer is passed, the map is simply compressed.
Returns
true - The shared memory was resized.
false - The shared memory could not be resized, errno holds reason.

Definition at line 311 of file XrdSsiShMap.icc.

312 {
314  XrdSsiShMat::CRZParms crzParms;
315 
316 // First see if this object is already attached.
317 //
318  if (!shMat) {errno = ENOTCONN; return false;}
319 
320 // Check if we need to supply default parms else copy over the parm list
321 //
322  if (parms)
323  {crzParms.indexSz = parms->indexSize;
324  crzParms.maxKeys = parms->maxKeys;
325  crzParms.maxKLen = parms->maxKeyLen;
326  crzParms.mode = parms->mode;
327  if (parms->options & XrdSsi::ShMap_Parms::ReUse)
328  crzParms.reUse =
329  (parms->options & ~XrdSsi::ShMap_Parms::noReUse ? 1 : 0);
330  if (parms->options & XrdSsi::ShMap_Parms::MultW)
331  crzParms.multW =
332  (parms->options & ~XrdSsi::ShMap_Parms::noMultW ? 1 : 0);
333  }
334 
335 // Do the resize
336 //
337  return shMat->Resize(crzParms);
338 }
virtual bool Resize(CRZParms &parms)=0
static const int ForResize
Constructor suitable for Resize() (use ShMap_Parms(ForResize)).
Definition: XrdSsiShMap.hh:94

References XrdSsi::ShMap_Parms::ForResize, XrdSsi::ShMap_Parms::indexSize, XrdSsiShMat::CRZParms::indexSz, XrdSsi::ShMap_Parms::maxKeyLen, XrdSsi::ShMap_Parms::maxKeys, XrdSsiShMat::CRZParms::maxKeys, XrdSsiShMat::CRZParms::maxKLen, XrdSsi::ShMap_Parms::mode, XrdSsiShMat::CRZParms::mode, XrdSsi::ShMap_Parms::MultW, XrdSsiShMat::CRZParms::multW, XrdSsi::ShMap_Parms::options, XrdSsi::ShMap_Parms::ReUse, and XrdSsiShMat::CRZParms::reUse.

◆ Sync()

template<class T >
bool XrdSsi::ShMap< T >::Sync ( XrdSsi::SyncOpt  dosync,
int  syncqsz = 256 
)

Specify how the memory map is synchronized with its backing file. If sync is already enabled, calling this method writes back any modified pages before effecting any requested changes.

Parameters
dosyncControls how synchronization is done (see SyncOpt enum): SyncOff - Turn synchronization off (initial setting). SyncOn - Turn synchronization on; pages are written in the background (i.e. asynchronously). SyncAll - Turn synchronization on; pages are written in the foreground(i.e. synchronously). SyncNow - Write back any queued pages but otherwise keep all other settings the same. SyncQSz - Set the queue size specified in the second argument. This number of modified pages are queued before being written back to disk. No other setting in effect are altered.
syncqszSpecifies the defer-writeback queue size. This argument is ignored unless SyncQSz has been specified (see above).
Returns
true - Call ended successfully.
false - Call failed; the errno value describes why.

Definition at line 345 of file XrdSsiShMap.icc.

346 {
347 // Make sure we have memory
348 //
349  if (!shMat) {errno = ENOTCONN; return false;}
350 
351 // Perform desired action
352 //
353  switch(dosync)
354  {case SyncOff: return shMat->Sync(false, false);
355  break;
356  case SyncOn: return shMat->Sync(true, false);
357  break;
358  case SyncAll: return shMat->Sync(true, true);
359  break;
360  case SyncNow: return shMat->Sync();
361  break;
362  case SyncQSz: return shMat->Sync(syncqsz);
363  break;
364  default: errno = EINVAL; return false;
365  break;
366  }
367  return false;
368 }
virtual bool Sync()=0

References XrdSsi::SyncAll, XrdSsi::SyncNow, XrdSsi::SyncOff, XrdSsi::SyncOn, and XrdSsi::SyncQSz.


The documentation for this class was generated from the following files: