map.h File Reference

Programs can use maps to store key/value pairs in a persistence store. More...

Macros
#define	TIB_MAP_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION   "com.tibco.ftl.client.map.persistence.retry.duration"
	Retry duration for map operations; double. More...
#define	TIB_MAP_PROPERTY_STRING_LABEL   "com.tibco.ftl.client.map.label"
	Property name for a map label; string. More...

Typedefs
typedef struct __tibMapId *	tibMap

Functions
TIB_API void	tibMap_Close (tibEx e, tibMap tibmap)
	Destroy a map object. More...
TIB_API tibMapIterator	tibMap_CreateIterator (tibEx e, tibMap tibmap, tibProperties props)
	Create an iterator over the keys in a map. More...
TIB_API tibMapIterator	tibMap_CreateIteratorWithLock (tibEx e, tibMap tibmap, tibLock lock, tibProperties props)
	Create an iterator over the keys in a map and associate it with a lock. More...
TIB_API tibMessage	tibMap_Get (tibEx e, tibMap tibmap, const char *key)
	Get the value of a key in a map. More...
TIB_API void	tibMap_GetMultiple (tibEx e, tibMap tibmap, tibint32_t numKeys, const char **keys, tibMessage *values)
	Get the values for the specified keys from a map. More...
TIB_API void	tibMap_GetMultipleWithLock (tibEx e, tibMap tibmap, tibint32_t numKeys, const char **keys, tibMessage *values, tibLock lock)
	Get the values for the specified keys from a map as a locked operation. More...
TIB_API tibint32_t	tibMap_GetName (tibEx e, tibMap id, char *buf, tibint32_t size)
	Return the name of the map. More...
TIB_API tibint64_t	tibMap_GetSize (tibEx e, tibMap id)
	Return map size. More...
TIB_API tibint64_t	tibMap_GetSizeWithLock (tibEx e, tibMap id, tibLock lock)
	Return map size as a locked operation. More...
TIB_API tibMessage	tibMap_GetWithLock (tibEx e, tibMap tibmap, const char *key, tibLock lock)
	Get the value of a key in a map as a locked operation. More...
TIB_API void	tibMap_Remove (tibEx e, tibMap tibmap, const char *key)
	Remove a key/value pair from a map. More...
TIB_API void	tibMap_RemoveAll (tibEx e, tibMap tibmap)
	Remove all key/value pairs from a map. More...
TIB_API void	tibMap_RemoveAllWithLock (tibEx e, tibMap tibmap, tibLock lock)
	Remove all key/value pairs from a map as a locked operation. More...
TIB_API void	tibMap_RemoveWithLock (tibEx e, tibMap tibmap, const char *key, tibLock lock)
	Remove a key/value pair from a map as a locked operation. More...
TIB_API void	tibMap_Set (tibEx e, tibMap tibmap, const char *key, tibMessage value)
	Set a key/value pair in a map. More...
TIB_API void	tibMap_SetMultiple (tibEx e, tibMap tibmap, tibint32_t numKeys, const char **keys, tibMessage *values)
	Set multiple key/value pairs in a map. More...
TIB_API void	tibMap_SetMultipleWithLock (tibEx e, tibMap tibmap, tibint32_t numKeys, const char **keys, tibMessage *values, tibLock lock)
	Set multiple key/value pairs in a map as a locked operation. More...
TIB_API void	tibMap_SetWithLock (tibEx e, tibMap tibmap, const char *key, tibMessage value, tibLock lock)
	Set a key/value pair in a map as a locked operation. More...

Detailed Description

Programs can use maps to store key/value pairs in a persistence store.

To create a map object, see tibRealm_CreateMap.
To delete a map from a store, see tibRealm_RemoveMap.

Prerequisite: Administrators must enable dynamic last-value durables in a persistence store. For more information, see TIBCO FTL Administration.

This file defines map calls.

Macro Definition Documentation

TIB_MAP_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

#define TIB_MAP_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION   "com.tibco.ftl.client.map.persistence.retry.duration"

Retry duration for map operations; double.

When tibRealm_CreateMap, tibMap_Set, tibMap_SetMultiple, tibMap_Get, tibMap_Remove, tibMap_RemoveAll, or tibMap_GetSize (with lock or without lock) cannot access the persistence server (usually because of network failure or quorum unavailability), they can automatically retry the interaction. The value of this property overrides the retry behavior of the server. Supply it to the map create call.

Values:

• 0 No retry. The call raises an exception.
• -1 Synchronously retry the interaction until it succeeds. The call returns only upon success.
• n (Any positive double value) Retry the interaction for n seconds. Return upon success or raise an exception after timeout.

Closing the realm or destroying the map supersedes and cancels retry behavior.

This property does not apply to map iterators.

TIB_MAP_PROPERTY_STRING_LABEL

#define TIB_MAP_PROPERTY_STRING_LABEL   "com.tibco.ftl.client.map.label"

Property name for a map label; string.

It is good practice to include this property in every map create call. Monitoring data incorporates these labels so administrators can identify and distinguish among internal publishers and subscribers created on behalf of maps. Use labels that reveal the unique role and identity of each map within the application program.

When the map label is present in the map create call, the new map assigns it as the label of its internal publishers and subscribers.

tibRealm_CreateMap

Typedef Documentation

tibMap

typedef struct __tibMapId* tibMap

Function Documentation

tibMap_Close()

TIB_API void tibMap_Close	(	tibEx	e,
		tibMap	tibmap
	)

Destroy a map object.

This call destroys only the local map object in the client process. To delete the map from the persistence store, see tibRealm_RemoveMap.

Parameters

e	The exception object captures information about failures.
tibmap	The call destroys this map object.

tibMap_CreateIterator()

TIB_API tibMapIterator tibMap_CreateIterator	(	tibEx	e,
		tibMap	tibmap,
		tibProperties	props
	)

Create an iterator over the keys in a map.

The iterator produces every key/value pair in the map.

Parameters

e	The exception object captures information about failures.
tibmap	This map object is the one used to create an iterator. The iterator can then iterate over the keys of the given map object.
props	Optional. NULL to omit. String matcher properties: TIB_MAPITER_PROPERTY_STRING_MATCHER

Returns

A map iterator object.

tibMap_CreateIteratorWithLock()

TIB_API tibMapIterator tibMap_CreateIteratorWithLock	(	tibEx	e,
		tibMap	tibmap,
		tibLock	lock,
		tibProperties	props
	)

Create an iterator over the keys in a map and associate it with a lock.

The iterator produces every key/value pair in the map.

Before its map operation, this call ensures that the process holds the lock. If the lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, if the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call sets an exception and returns null.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

Subsequent calls to advance the iterator require that the process hold the lock.

Parameters

e	The exception object captures information about failures.
tibmap	This map object is the one used to create an iterator. The iterator can then iterate over the keys of the given map object.
lock	The iterator uses the lock represented by this lock object.
props	Optional. NULL to omit. String matcher properties: TIB_MAPITER_PROPERTY_STRING_MATCHER

Returns

A map iterator object.

tibMap_Get()

TIB_API tibMessage tibMap_Get	(	tibEx	e,
		tibMap	tibmap,
		const char *	key
	)

Get the value of a key in a map.

This call returns a copy of the stored message. Client program code accepts ownership of the message object. Client program code may pass this message to another program thread. Client program code must explicitly destroy the message object.

If the key is not set in the map, this call returns null.

Parameters

e	The exception object captures information about failures.
tibmap	The call gets the key's value in this map.
key	The call gets a value for this key.

Returns

A message.

tibMap_GetMultiple()

TIB_API void tibMap_GetMultiple	(	tibEx	e,
		tibMap	tibmap,
		tibint32_t	numKeys,
		const char **	keys,
		tibMessage *	values
	)

Get the values for the specified keys from a map.

The values array will be populated by the library; The caller must allocate the values array. An entry of NULL in the values array means that no value is present for the key at the corresponding index of the keys array. If an exception is set the entries in the values array can't be relied upon.

Parameters

e	The exception object captures information about failures.
tibmap	The call returns the value associted with the keys from this map.
numKeys	The total number keys whose values to return.
keys	The call gets values for the specfied keys.
values	The values array is populated by the library.

tibMap_GetMultipleWithLock()

TIB_API void tibMap_GetMultipleWithLock	(	tibEx	e,
		tibMap	tibmap,
		tibint32_t	numKeys,
		const char **	keys,
		tibMessage *	values,
		tibLock	lock
	)

Get the values for the specified keys from a map as a locked operation.

Before its map operation, this call ensures that the process holds the lock. If the lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, if the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call sets an exception, and does not return any values.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

The values array will be populated by the library; The caller must allocate the values array. An entry of NULL in the values array means that no value is present for the key at the corresponding index of the keys array. If an exception is set the entries in the values array can't be relied upon.

Parameters

e	The exception object captures information about failures.
tibmap	The call returns the value associted with the keys from this map.
numKeys	The total number keys whose values to return.
keys	The call gets values for these keys.
values	The values array is populated by the library.
lock	The call uses the lock represented by this lock object.

tibMap_GetName()

TIB_API tibint32_t tibMap_GetName	(	tibEx	e,
		tibMap	id,
		char *	buf,
		tibint32_t	size
	)

Return the name of the map.

Parameters

e	The exception object captures information about failures.
tibmap	The call returns the size of this map.
buf	The call stores the name in this string buffer.
size	The program supplies the length of buffer (in bytes).

tibMap_GetSize()

TIB_API tibint64_t tibMap_GetSize	(	tibEx	e,
		tibMap	id
	)

Return map size.

Return the number of key/value pairs in the map.

Parameters

e	The exception object captures information about failures.
tibmap	The call returns the size of this map.

tibMap_GetSizeWithLock()

TIB_API tibint64_t tibMap_GetSizeWithLock	(	tibEx	e,
		tibMap	id,
		tibLock	lock
	)

Return map size as a locked operation.

Before its map operation, this call ensures that the process holds the lock. If the lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, if the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call sets an exception.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

Return the number of key/value pairs in the map using a specified lock.

Parameters

e	The exception object captures information about failures.
tibmap	The call returns the size of this map.
lock	The call uses the lock represented by this lock object.

tibMap_GetWithLock()

TIB_API tibMessage tibMap_GetWithLock	(	tibEx	e,
		tibMap	tibmap,
		const char *	key,
		tibLock	lock
	)

Get the value of a key in a map as a locked operation.

This call returns a copy of the stored message. Client program code accepts ownership of the message object. Client program code may pass this message to another program thread. Client program code must explicitly destroy the message object.

Before its map operation, this call ensures that the process holds the lock. If the lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, if the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call sets an exception and returns null.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

If the key is not set in the map, this call returns null.

Parameters

e	The exception object captures information about failures.
tibmap	The call gets the key's value in this map.
key	The call gets a value for this key.
lock	The call requires the lock represented by this lock object.

Returns

A message.

tibMap_Remove()

TIB_API void tibMap_Remove	(	tibEx	e,
		tibMap	tibmap,
		const char *	key
	)

Remove a key/value pair from a map.

Parameters

e	The exception object captures information about failures.
tibmap	The call removes the key from this map.
key	The call removes this key.

tibMap_RemoveAll()

TIB_API void tibMap_RemoveAll	(	tibEx	e,
		tibMap	tibmap
	)

Remove all key/value pairs from a map.

This call does not destroy the map.

Parameters

e	The exception object captures information about failures.
tibmap	The call removes the key/value pairs from this map.

tibMap_RemoveAllWithLock()

TIB_API void tibMap_RemoveAllWithLock	(	tibEx	e,
		tibMap	tibmap,
		tibLock	lock
	)

Remove all key/value pairs from a map as a locked operation.

Before its map operation, this call ensures that the process holds the lock. If the lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, if the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call sets an exception, and does not remove the key/value pairs.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

This call does not destroy the map.

Parameters

e	The exception object captures information about failures.
tibmap	The call removes the key/value pairs from this map.
lock	The call requires the lock represented by this lock object.

tibMap_RemoveWithLock()

TIB_API void tibMap_RemoveWithLock	(	tibEx	e,
		tibMap	tibmap,
		const char *	key,
		tibLock	lock
	)

Remove a key/value pair from a map as a locked operation.

Before its map operation, this call ensures that the process holds the lock. If the lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, if the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call sets an exception, and does not remove the key/value pair.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

Parameters

e	The exception object captures information about failures.
tibmap	The call removes the key from this map.
key	The call removes this key.
lock	The call requires the lock represented by this lock object.

tibMap_Set()

TIB_API void tibMap_Set	(	tibEx	e,
		tibMap	tibmap,
		const char *	key,
		tibMessage	value
	)

Set a key/value pair in a map.

If a value has already been set for the key, this call overwrites the existing value.

Parameters

e	The exception object captures information about failures.
tibmap	The call stores the key/value pair in this map.
key	The call sets a value for this key.
value	The call sets this value for the key.

tibMap_SetMultiple()

TIB_API void tibMap_SetMultiple	(	tibEx	e,
		tibMap	tibmap,
		tibint32_t	numKeys,
		const char **	keys,
		tibMessage *	values
	)

Set multiple key/value pairs in a map.

If a value has already been set for a key, this call overwrites the existing value.

Parameters

e	The exception object captures information about failures.
tibmap	The call stores the key/value pairs in this map.
numKeys	Number of keys/value pairs to store.
keys	The call sets values for these keys.
values	The call sets these values for the corresponding keys.

tibMap_SetMultipleWithLock()

TIB_API void tibMap_SetMultipleWithLock	(	tibEx	e,
		tibMap	tibmap,
		tibint32_t	numKeys,
		const char **	keys,
		tibMessage *	values,
		tibLock	lock
	)

Set multiple key/value pairs in a map as a locked operation.

Before its map operation, this call ensures that the process holds the lock. If the lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, if the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call sets an exception, and does not change any values.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

If a value has already been set for a key, this call overwrites the existing value.

Parameters

e	The exception object captures information about failures.
tibmap	The call stores the key/value pairs in this map.
numKeys	Number of keys/value pairs to store.
keys	The call sets values for these keys.
values	The call sets these values the corresponding keys.
lock	The call requires the lock represented by this lock object.

tibMap_SetWithLock()

TIB_API void tibMap_SetWithLock	(	tibEx	e,
		tibMap	tibmap,
		const char *	key,
		tibMessage	value,
		tibLock	lock
	)

Set a key/value pair in a map as a locked operation.

Before its map operation, this call ensures that the process holds the lock. If the lock was previously held and then broken, this call fails until the lock is returned or a new lock object is supplied. Otherwise, if the process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call sets an exception, and does not change the key's value.

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until the lock is explicitly returned or the lock is broken. A disconnect from the persistence service or a call to steal the lock can break the lock owned by this process.

If a value has already been set for the key, this call overwrites the existing value.

Parameters

e	The exception object captures information about failures.
tibmap	The call stores the key/value pair in this map.
key	The call sets a value for this key.
value	The call sets this value for the key.
lock	The call requires the lock represented by this lock object.