class CAVERN_irbKey_c

CAVERN IRB Key class

Public Classes

enum CAVERN_irbKeyBlocking_t
Used to specify if specific key operations should block till completion or not (See put(), deliver(), deliverIncludingPassive())
BLOCKING
Blocking.
NON_BLOCKING
Non-blocking.
enum CAVERN_irbKeyEvent_t
Trigger event types for keys.
NEW_DATA_ARRIVED
New data has arrived at the key.
enum CAVERN_irbKeyTrigger_t
Used to specify that when the data eventually reaches its destination, whether to call the key's trigger callback function via a separately spawned thread or not
NON_THREADED_TRIGGER
Non-threaded trigger.
THREADED_TRIGGER
Threaded trigger.
enum status_t
Status codes returned from CAVERN_irbKey_c methods.
OK
Operation succeeded.
FAILED
Operation failed.
KEY_STALE
Access to the key failed because the key is no longer valid; delete the key and redefine it if you wish to access it
BUFFER_TOO_SMALL
Returned if you attempt a get() but did not provide a large enough buffer for CAVERNsoft to store the data into

Public Methods

void allocDirect (char *&direct, int *sze, CAVERN_irbKey_c::status_t *status)
Similar to getDirect
void commit (CAVERN_irbKey_c::status_t *status)
Commit the local key to persistent store
void deliver (CAVERN_irbKey_c::status_t *status, CAVERN_irbKey_c::CAVERN_irbKeyBlocking_t blockingType = CAVERN_irbKey_c::NON_BLOCKING, CAVERN_irbKey_c::CAVERN_irbKeyTrigger_t triggerType = CAVERN_irbKey_c::NON_THREADED_TRIGGER)
Dispatch data inside current key
void deliverIncludingPassive (CAVERN_irbKey_c::status_t *status, CAVERN_irbKey_c::CAVERN_irbKeyBlocking_t blockingType = CAVERN_irbKey_c::NON_BLOCKING, CAVERN_irbKey_c::CAVERN_irbKeyTrigger_t triggerType = CAVERN_irbKey_c::NON_THREADED_TRIGGER)
This does the same thing as deliver except it delivers to passive links as well
void export (char *filename, CAVERN_irbKey_c::status_t *status)
Export a key to an output file
void get (char *bufferToFill, int *sze, CAVERN_irbKey_c::status_t *status)
Get a copy of the data from key
void getAutoAlloc (char *&autoAllocatedBuffer, int *sze, CAVERN_irbKey_c::status_t *status)
Get a copy of the data in the key but auto allocate memory for the buffer
void getDirect (char *&direct, int *sze, CAVERN_irbKey_c::status_t *status)
Get the direct pointer to the data in the key
CAVERN_irbKeyId_c getKeyId ()
Get a copy of the key Id that defined this key.
void getMeta (char *bufferToFill, int *sze, CAVERN_irbKey_c::status_t *status)
Get a copy of the meta data from key
void getMetaSize (int *sze, CAVERN_irbKey_c::status_t *status)
Get the size of the meta data
void getSize (int *sze, CAVERN_irbKey_c::status_t *status)
Get size of data in key.
void import (char *filename, int *sze, CAVERN_irbKey_c::status_t *status, CAVERN_irbKey_c::CAVERN_irbKeyBlocking_t blockingType = CAVERN_irbKey_c::NON_BLOCKING, CAVERN_irbKey_c::CAVERN_irbKeyTrigger_t triggerType = CAVERN_irbKey_c::NON_THREADED_TRIGGER)
Import data into key from a file
void import (char *filename, int *sze, char* metaData, int *metaSize, CAVERN_irbKey_c::status_t *status, CAVERN_irbKey_c::CAVERN_irbKeyBlocking_t blockingType = CAVERN_irbKey_c::NON_BLOCKING, CAVERN_irbKey_c::CAVERN_irbKeyTrigger_t triggerType = CAVERN_irbKey_c::NON_THREADED_TRIGGER)
Import data into key from a file
void put (char *buffer, int *sze, char* metaData, int* metaSize, CAVERN_irbKey_c::status_t *status, CAVERN_irbKey_c::CAVERN_irbKeyBlocking_t blockingType = CAVERN_irbKey_c::NON_BLOCKING, CAVERN_irbKey_c::CAVERN_irbKeyTrigger_t triggerType = CAVERN_irbKey_c::NON_THREADED_TRIGGER)
Put data into key
void put (char *buffer, int *sze, CAVERN_irbKey_c::status_t *status, CAVERN_irbKey_c::CAVERN_irbKeyBlocking_t blockingType = CAVERN_irbKey_c::NON_BLOCKING, CAVERN_irbKey_c::CAVERN_irbKeyTrigger_t triggerType = CAVERN_irbKey_c::NON_THREADED_TRIGGER)
Put data into key
void releaseDirect (CAVERN_irbKey_c::status_t *status)
Release the pointer to the data in the key
void setMeta (char *meta, int *size, CAVERN_irbKey_c::status_t *status)
Set the meta data field of a key
void trigger (void (*callback)(CAVERN_irbKey_c::CAVERN_irbKeyEvent_t event, CAVERN_irbKey_c *thisKey, void* userData), void* userData)
Trigger on an event
~CAVERN_irbKey_c ()
The destructor will dereference the local key so that it may be garbage collected to free up CAVERN's resources

Public

enum CAVERN_irbKeyBlocking_t
Used to specify if specific key operations should block till completion or not (See put(), deliver(), deliverIncludingPassive())
BLOCKING
Blocking.
NON_BLOCKING
Non-blocking.
enum CAVERN_irbKeyEvent_t
Trigger event types for keys.
NEW_DATA_ARRIVED
New data has arrived at the key.
enum CAVERN_irbKeyTrigger_t
Used to specify that when the data eventually reaches its destination, whether to call the key's trigger callback function via a separately spawned thread or not
NON_THREADED_TRIGGER
Non-threaded trigger.
THREADED_TRIGGER
Threaded trigger.
enum status_t
Status codes returned from CAVERN_irbKey_c methods.
OK
Operation succeeded.
FAILED
Operation failed.
KEY_STALE
Access to the key failed because the key is no longer valid; delete the key and redefine it if you wish to access it
BUFFER_TOO_SMALL
Returned if you attempt a get() but did not provide a large enough buffer for CAVERNsoft to store the data into

Documentation

CAVERN IRB Key class. Objects of this type are instantiated by calling CAVERN_irb_c::define(). When you are done refering to the key delete it to free up system resources.
~CAVERN_irbKey_c()
The destructor will dereference the local key so that it may be garbage collected to free up CAVERN's resources. Hence it is a way to undefine a key. There is currently no call to undefine a key permanently including the persistent store.

enum CAVERN_irbKeyTrigger_t
Used to specify that when the data eventually reaches its destination, whether to call the key's trigger callback function via a separately spawned thread or not. In general if you have small pieces of data updating rapidly you should use a non-threaded trigger to prevent the IRB from over spawning threads and crashing the IRB. If you intend to infrequently send large pieces of data via a key then a threaded trigger would be desirable.
See Also:
put(), import(), deliver(), deliverIncludingPassive().

void put(char *buffer, int *sze, CAVERN_irbKey_c::status_t *status, CAVERN_irbKey_c::CAVERN_irbKeyBlocking_t blockingType = CAVERN_irbKey_c::NON_BLOCKING, CAVERN_irbKey_c::CAVERN_irbKeyTrigger_t triggerType = CAVERN_irbKey_c::NON_THREADED_TRIGGER)
Put data into key. This replaces the previous contents with the new contents. This call usually results in a copy of the entire data to the remote site.
Parameters:
buffer - gets copied to key.
sze - amount of data to copy. Returns sze successfully copied.
status - returns status: FAIL occurs if any general problems occurred (like internal mem allocation) KEY_STALE occurs if this key is no longer valid for data access. OK is returned if the put is successful.
blockingType - if set to BLOCKING will return only after the data has been delivered, otherwise this function will return immediately after having initiated delivery. Blocking is ususually used if you don't wish to continue with the flow of your program until a piece of data has been guaranteed to be delivered to the destination. For example you would perform a blocking put before you did a remoteCommit on a link.
triggerType - if set to THREADED_TRIGGER, the threaded handler will be called; if set to NON_THREADED_TRIGGER, the non-threaded handler will be called. See CAVERN_irbKeyTrigger_t for more details.

void put(char *buffer, int *sze, char* metaData, int* metaSize, CAVERN_irbKey_c::status_t *status, CAVERN_irbKey_c::CAVERN_irbKeyBlocking_t blockingType = CAVERN_irbKey_c::NON_BLOCKING, CAVERN_irbKey_c::CAVERN_irbKeyTrigger_t triggerType = CAVERN_irbKey_c::NON_THREADED_TRIGGER)
Put data into key. This replaces the previous contents with the new contents. This call usually results in a copy of the entire data to the remote site.
Parameters:
buffer - gets copied to key.
sze - amount of data to copy. Returns num of bytes successfully copied.
metaData - assigns meta data field of a key. Meta data means data about the data. Meta data is intended to be small. One e.g. of its use is to send type information about the data in a key.
metaSize - size of meta data. Returns num of bytes successfully copied.
status - returns status: FAIL occurs if any general problems occurred (like internal mem allocation) KEY_STALE occurs if this key is no longer valid for data access. OK is returned if the put is successful.
blockingType - if set to BLOCKING will return only after the data has been delivered, otherwise this function will return immediately after having initiated delivery. Blocking is ususually used if you don't wish to continue with the flow of your program until a piece of data has been guaranteed to be delivered to the destination. For example you would perform a blocking put before you did a remoteCommit on a link.
triggerType - if set to THREADED_TRIGGER, the threaded handler will be called; if set to NON_THREADED_TRIGGER, the non-threaded handler will be called. See CAVERN_irbKeyTrigger_t for more details.

void import(char *filename, int *sze, CAVERN_irbKey_c::status_t *status, CAVERN_irbKey_c::CAVERN_irbKeyBlocking_t blockingType = CAVERN_irbKey_c::NON_BLOCKING, CAVERN_irbKey_c::CAVERN_irbKeyTrigger_t triggerType = CAVERN_irbKey_c::NON_THREADED_TRIGGER)
Import data into key from a file. This replaces the previous contents with the new contents. This call usually results in a copy of the entire data to the remote site.
Parameters:
filename - specifies the file to load.
sze - this returns the size of the file loaded.
status - returns status: FAIL occurs if any general problems occurred (like internal mem allocation) KEY_STALE occurs if this key is no longer valid for data access. OK is returned if the put is successful.
blockingType - if set to BLOCKING will return only after the data has been delivered, otherwise this function will return immediately after having initiated delivery. Blocking is ususually used if you don't wish to continue with the flow of your program until a piece of data has been guaranteed to be delivered to the destination. For example you would perform a blocking put before you did a remoteCommit on a link.
triggerType - if set to THREADED_TRIGGER, the threaded handler will be called; if set to NON_THREADED_TRIGGER, the non-threaded handler will be called. See CAVERN_irbKeyTrigger_t for more details.

void import(char *filename, int *sze, char* metaData, int *metaSize, CAVERN_irbKey_c::status_t *status, CAVERN_irbKey_c::CAVERN_irbKeyBlocking_t blockingType = CAVERN_irbKey_c::NON_BLOCKING, CAVERN_irbKey_c::CAVERN_irbKeyTrigger_t triggerType = CAVERN_irbKey_c::NON_THREADED_TRIGGER)
Import data into key from a file. This replaces the previous contents with the new contents. This call usually results in a copy of the entire data to the remote site.
Parameters:
filename - specifies the file to load.
sze - this returns the size of the file loaded.
metaData - assigns meta data field of a key. Meta data means data about the data. Meta data is intended to be small. One e.g. of its use is to send type information about the data in a key.
metaSize - size of meta data. Returns num of bytes successfully copied.
status - returns status: FAIL occurs if any general problems occurred (like internal mem allocation) KEY_STALE occurs if this key is no longer valid for data access. OK is returned if the put is successful.
blockingType - if set to BLOCKING will return only after the data has been delivered, otherwise this function will return immediately after having initiated delivery. Blocking is ususually used if you don't wish to continue with the flow of your program until a piece of data has been guaranteed to be delivered to the destination. For example you would perform a blocking put before you did a remoteCommit on a link.
triggerType - if set to THREADED_TRIGGER, the threaded handler will be called; if set to NON_THREADED_TRIGGER, the non-threaded handler will be called. See CAVERN_irbKeyTrigger_t for more details.

void export(char *filename, CAVERN_irbKey_c::status_t *status)
Export a key to an output file
Parameters:
status - returns either OK or FAILED. KEY_STALE is returned if this key is no longer valid for data access.
filename - is output file to export to.

void get(char *bufferToFill, int *sze, CAVERN_irbKey_c::status_t *status)
Get a copy of the data from key
Parameters:
bufferToFill - is a user provided buffer into which the data is copied.
sze - is the size of the data buffer provided. Sze returns the size of the data copied into the buffer.
status - returns status: BUFFER_TOO_SMALL occurs when the data in the key is larger than data buffer provided by user. OK if everything was fine. KEY_STALE if for some reason this key is no longer active.

void getMetaSize(int *sze, CAVERN_irbKey_c::status_t *status)
Get the size of the meta data. Meta data means data about the data. Meta data is intended to be small. One e.g. of its use is to send type information about the data in a key.

void setMeta(char *meta, int *size, CAVERN_irbKey_c::status_t *status)
Set the meta data field of a key
Parameters:
meta - assigns meta data field of a key. Meta data means data about the data. Meta data is intended to be small. One e.g. of its use is to send type information about the data in a key.
size - is size of meta data. Returns num of bytes successfully copied.

void getMeta(char *bufferToFill, int *sze, CAVERN_irbKey_c::status_t *status)
Get a copy of the meta data from key. Meta data means data about the data. Meta data is intended to be small. One e.g. of its use is to send type information about the data in a key.
Parameters:
bufferToFill - is a user provided buffer into which the meta data is copied.
sze - is the size of the data buffer provided. Sze returns the size of the meta data copied into the buffer.
status - returns status: BUFFER_TOO_SMALL occurs when the meta data in the key is larger than data buffer provided by user. OK if everything was fine. KEY_STALE if for some reason this key is no longer active.

void getAutoAlloc(char *&autoAllocatedBuffer, int *sze, CAVERN_irbKey_c::status_t *status)
Get a copy of the data in the key but auto allocate memory for the buffer. I.e. you give it a plain pointer and it will return a chunk of memory. The returned buffer must be manually deleted by you. If memory could not be allocated the buffer returns NULL, the size returns 0.
Parameters:
status - returns OK if everything was fine. Returns FAILED if a memory allocation problem occurred. Returns KEY_STALE if the this key is no longer valid.

void getDirect(char *&direct, int *sze, CAVERN_irbKey_c::status_t *status)
Get the direct pointer to the data in the key. Use this with CAUTION. This forces a lock on CAVERNsoft's internal database so it could potentially prevent new incoming data from arriving. Use the data and release the resource with releaseDirect() as quickly as possible.
Parameters:
status - returns OK or KEY_STALE.
See Also:
releaseDirect()

void allocDirect(char *&direct, int *sze, CAVERN_irbKey_c::status_t *status)
Similar to getDirect. This function allocates memory in the key of a size specified by the sze parameter. Sze also returns the sze of the data successfully allocated. Direct is a pointer to the allocated memory. Use this with CAUTION. This forces a lock on CAVERNsoft's internal database so it could potentially prevent new incoming data from arriving. Use the data and release the resource with releaseDirect() as quickly as possible.

Typical use of this function is:

aKey->allocDirect(buffer,....);

fillBufferWithData(buffer);

aKey->releaseDirect();

aKey->deliver(......);

Warning. There is currently nothing that guarantees that the data in the key won't be updated by new incoming data between the time of releaseDirect() and deliver().

Parameters:
status - returns OK, KEY_STALE or FAILED
See Also:
releaseDirect()

void releaseDirect(CAVERN_irbKey_c::status_t *status)
Release the pointer to the data in the key. See getDirect(). At the present time, multiple successive calls to releaseDirect can produce undefined behavior.
Parameters:
status - returns either OK or KEY_STALE.

void commit(CAVERN_irbKey_c::status_t *status)
Commit the local key to persistent store. If you wish to commit a remote key to persistent store see CAVERN_irbLink_c::commitRemote().

void deliver(CAVERN_irbKey_c::status_t *status, CAVERN_irbKey_c::CAVERN_irbKeyBlocking_t blockingType = CAVERN_irbKey_c::NON_BLOCKING, CAVERN_irbKey_c::CAVERN_irbKeyTrigger_t triggerType = CAVERN_irbKey_c::NON_THREADED_TRIGGER)
Dispatch data inside current key. It ensures that if this key is participating in a link it will dispatch its changes to all the remote connections. This is good to do after data is modified with getDirect and releaseDirect since these calls have no knowledge of whether you have modified the key or not.

Delivery abides by the constraints set by CAVERN_linkAttrib_c during the creation of the link.

See CAVERN_irbLink_c and CAVERN_linkAttrib_c.

Parameters:
status - returns either OK or KEY_STALE.
blockingType - if set to BLOCKING will return only after the data has been delivered, otherwise this function will return immediately after having initiated delivery. Blocking is ususually used if you don't wish to continue with the flow of your program until a piece of data has been guaranteed to be delivered to the destination. For example you would perform a blocking put before you did a remoteCommit on a link.
triggerType - if set to THREADED_TRIGGER, the threaded handler will be called; if set to NON_THREADED_TRIGGER, the non-threaded handler will be called. See CAVERN_irbKeyTrigger_t for more details.

void deliverIncludingPassive(CAVERN_irbKey_c::status_t *status, CAVERN_irbKey_c::CAVERN_irbKeyBlocking_t blockingType = CAVERN_irbKey_c::NON_BLOCKING, CAVERN_irbKey_c::CAVERN_irbKeyTrigger_t triggerType = CAVERN_irbKey_c::NON_THREADED_TRIGGER)
This does the same thing as deliver except it delivers to passive links as well. See CAVERN_irbLink_c.
Parameters:
status - returns either OK or KEY_STALE.
blockingType - if set to BLOCKING will return only after the data has been delivered, otherwise this function will return immediately after having initiated delivery. Blocking is ususually used if you don't wish to continue with the flow of your program until a piece of data has been guaranteed to be delivered to the destination. For example you would perform a blocking put before you did a remoteCommit on a link.
triggerType - if set to THREADED_TRIGGER, the threaded handler will be called; if set to NON_THREADED_TRIGGER, the non-threaded handler will be called. See CAVERN_irbKeyTrigger_t for more details.

void trigger(void (*callback)(CAVERN_irbKey_c::CAVERN_irbKeyEvent_t event, CAVERN_irbKey_c *thisKey, void* userData), void* userData)
Trigger on an event. This will call a user-provided callback when an event occurs. See CAVERN_irbKeyEvent_t. WARNING: Currently you cannot perform a put() or any of the deliver() calls on this same key while you are in the user's callback [get() calls are ok.] This is because the key is locked to protect other clients from writing to your key while you are reading it. Hopefully soon we will come up with a solution for this.

Also note that when this CAVERN_irbKey_c object is deleted the trigger is also removed. Even if you have other CAVERN_irbKey_c objects that are defined to the same path and key, the trigger is always associated with the object that performed the trigger() call.

Parameters:
callback - is the callback to call when trigger occurs. Callback is of the form: void myCallback(CAVERN_irbKey_c::CAVERN_irbKeyEvent_t event, CAVERN_irbKey_c *thisKey, void* userData);
userData - is address of data to pass into callback.


This class has no child classes.

alphabetic index hierarchy of classes


this page has been generated automatically by doc++

(c)opyright by Malte Zöckler, Roland Wunderling
contact: doc++@zib.de