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 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_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_Get, or tibMap_Remove (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	The call destroys this map object.
props	Reserved for future use. To ensure forward compatibility, programmers must supply NULL.

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 creating an iterator, this call ensures that the process holds the lock. 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 throws an exception, and does not create an iterator.

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

If the process acquires the lock through this call, it retains the lock after the call completes. The process holds the lock until it explicitly returns it.

Parameters

e	The exception object captures information about failures.
tibmap	The call destroys this map object.
lock	The iterator uses the lock represented by this lock object.
props	Reserved for future use. To ensure forward compatibility, programmers must supply NULL.

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_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 process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call throws an exception, and does not return 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 it explicitly returns it.

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_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 process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call throws an exception, and does not remove 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 it explicitly returns it.

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 process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call throws 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 it explicitly returns it.

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 process does not already hold the lock, this call acquires the lock for the process. If it cannot acquire the lock, this call throws 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 it explicitly returns it.

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.