#include <XrdSsiShMap.hh>

Collaboration diagram for XrdSsi::ShMap< T >:

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
XrdSsiShMat *	shMat

ShMap_Hash_t	hashFunc

char *	typeID

char *	implID

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.

◆ ~ShMap()

template<class T >

XrdSsi::ShMap< T >::~ShMap ( )

inline

Destructor.

References XrdSsi::ShMap< T >::Detach(), XrdSsi::ShMap< T >::implID, and XrdSsi::ShMap< T >::typeID.

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

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).

◆ Attach()

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.

◆ Create()

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

path	Pointer to the file that is or will represent the map.
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.

◆ Del()

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).

◆ Detach()

template<class T >

void XrdSsi::ShMap< T >::Detach ( )

Detach the map from the shared memory.

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

◆ 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

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.

◆ Enumerate() [2/2]

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.

◆ Exists()

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.

◆ 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.

◆ 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

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).

◆ Info()

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 ENOTSUP.

◆ 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

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).

◆ Resize()

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.

◆ Sync()

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

◆ hashFunc

template<class T >

ShMap_Hash_t XrdSsi::ShMap< T >::hashFunc

private

◆ implID

template<class T >

char* XrdSsi::ShMap< T >::implID

private

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

◆ shMat

template<class T >

XrdSsiShMat* XrdSsi::ShMap< T >::shMat

private

◆ typeID

template<class T >

char* XrdSsi::ShMap< T >::typeID

private

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

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

XrdSsiShMap.hh

Public Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ ShMap()

◆ ~ShMap()

Member Function Documentation

◆ Add()

◆ Attach()

◆ Create()

◆ Del()

◆ Detach()

◆ Enumerate() [1/2]

◆ Enumerate() [2/2]

◆ Exists()

◆ Export()

◆ Get()

◆ Info()

◆ Rep()

◆ Resize()

◆ Sync()

Member Data Documentation

◆ hashFunc

◆ implID

◆ shMat

◆ typeID