TIBCO FTL®

Macros | Typedefs | Functions
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_RemoveMultiple (tibEx e, tibMap id, tibint32_t numKeys, const char **keys)
| Remove multiple key/value pairs from a map. More...
TIB_API void | tibMap_RemoveMultipleWithLock (tibEx e, tibMap id, tibint32_t numKeys, const char **keys, tibLock lock)
| Remove multiple 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_RemoveMultiple()

TIB_API void tibMap_RemoveMultiple | ( | tibEx | e,
|  | tibMap | id,
|  | tibint32_t | numKeys,
|  | const char ** | keys
| ) |  |

Remove multiple key/value pairs from a map.

Removing multiple keys at once may offer better performance when compared to removing one key at a time.

Parameters

  e | The exception object captures information about failures.
  tibmap | The call removes the key/value pairs from this map.
  numKeys | Number of keys/value pairs to remove.
  keys | The call removes values for these keys.

## ◆ tibMap_RemoveMultipleWithLock()

TIB_API void tibMap_RemoveMultipleWithLock | ( | tibEx | e,
|  | tibMap | id,
|  | tibint32_t | numKeys,
|  | const char ** | keys,
|  | tibLock | lock
| ) |  |

Remove multiple 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 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.

Removing multiple keys at once may offer better performance when compared to removing one key at a time.

Parameters

  e | The exception object captures information about failures.
  tibmap | The call removes the key/value pairs from this map.
  numKeys | Number of keys/value pairs to remove.
  keys | The call removes values for these keys.
  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.