XRootD
Loading...
Searching...
No Matches
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.
 
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.
 
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}
#define access(a, b)
Definition XrdPosix.hh:39
const char * typeID
The name of the type associated with the key.
const char * impl
Implementation name.
static XrdSsiShMat * New(NewParms &parms)
const char * path
The path to the backing file for the table.
virtual bool Attach(int tout, bool isrw=false)=0
int hashID
The hash being used (0 means the default)
int typeSz
Size of the type in bytes.
@ ReadOnly
reading

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.
int maxKLen
The maximum acceptable key length.
int mode
Filemode for the newly created file.
int indexSz
Number of four byte hash table entries to create.
static const int MultW
Bit options that may be or'd into he options member above.
int maxKeys
Maximum expected keys.
int mode
Mode setting for the newly created file.
int maxKeyLen
Maximum key length.
static const int ReUse
Reuse map storage.
static const int noReUse
Opposite (default for Create)
static const int noMultW
Opposite (default for Create)
int options
Bit or'd ShMop_xxxx options below.
int indexSize
Number of hash table entries to create.

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;
328 crzParms.reUse =
329 (parms->options & ~XrdSsi::ShMap_Parms::noReUse ? 1 : 0);
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)).

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: