XrdSsi::ShMap< T > Class Template Reference

#include <XrdSsiShMap.hh>

Collaboration diagram for XrdSsi::ShMap< T >:
Collaboration graph
[legend]

List of all members.

Public Member Functions

bool Attach (const char *path, ShMap_Access access, int tmo=-1)
bool Create (const char *path, ShMap_Parms &parms)
void Detach ()
 Detach the map from the shared memory.
bool Export ()
bool Add (const char *key, T &val)
bool Del (const char *key, T *valP=0)
bool Enumerate (void *&jar, char *&key, T *&val)
bool Enumerate (void *&jar)
bool Exists (const char *key)
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)
 ShMap (const char *typeName, ShMap_Hash_t hFunc=0, const char *implName=0)
 ~ShMap ()
 Destructor.

Private Attributes

XrdSsiShMatshMat
ShMap_Hash_t hashFunc
char * typeID
char * implID

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


Constructor & Destructor Documentation

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.
template<class T >
XrdSsi::ShMap< T >::~ShMap (  )  [inline]

Member Function Documentation

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:
key pointer to the key of length <= MaxKeySize.
val The 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).
template<class T >
bool XrdSsi::ShMap< T >::Attach ( const char *  path,
ShMap_Access  access,
int  tmo = -1 
)

Attach an existing shared memory map.

Parameters:
path Pointer to the file that is or will represent the map.
access How 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
tmo How 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.
template<class T >
bool XrdSsi::ShMap< T >::Create ( const char *  path,
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:
parms Reference 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.
template<class T >
bool XrdSsi::ShMap< T >::Del ( const char *  key,
T *  valP = 0 
)

Delete an item from the map.

Parameters:
key Pointer to the key of length <= MaxKeySize.
valP Pointer 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).
template<class T >
void XrdSsi::ShMap< T >::Detach (  ) 

Detach the map from the shared memory.

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

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:
jar The 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.
template<class T >
bool XrdSsi::ShMap< T >::Enumerate ( void *&  jar,
char *&  key,
T *&  val 
)

Enumerate the keys and associated values.

Parameters:
jar An 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).
key The 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.
val The 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.
template<class T >
bool XrdSsi::ShMap< T >::Exists ( const char *  key  ) 

Determine whether or not a key exists in the map.

Parameters:
key Pointer to the key of length <= MaxKeySize.
Returns:
true - The key exists.
false - The key does not exist.
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.
template<class T >
bool XrdSsi::ShMap< T >::Get ( const char *  key,
T &  val 
)

Find a key in the map and return its value.

Parameters:
key Pointer to the key of length <= MaxKeySize.
val Reference 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).
template<class T >
int XrdSsi::ShMap< T >::Info ( const char *  vname,
char *  buff = 0,
int  blen = 0 
)

Return information about the map.

Parameters:
vname Pointer 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.
blen The 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 ENOSYS.
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:
key Pointer to the key of length <= MaxKeySize.
val The associated data to be added to or replaced in the map.
valP Pointer 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).
template<class T >
bool XrdSsi::ShMap< T >::Resize ( ShMap_Parms parms = 0  ) 

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

Parameters:
parms Pointer 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.
template<class T >
bool XrdSsi::ShMap< T >::Sync ( 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:
dosync Controls 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.
syncqsz Specifies 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.

Member Data Documentation

template<class T >
ShMap_Hash_t XrdSsi::ShMap< T >::hashFunc [private]
template<class T >
char* XrdSsi::ShMap< T >::implID [private]
template<class T >
XrdSsiShMat* XrdSsi::ShMap< T >::shMat [private]
template<class T >
char* XrdSsi::ShMap< T >::typeID [private]

The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 5 Feb 2020 for xrootd by  doxygen 1.6.1