hamsterdb Embedded Database 2.1.1
A generic key.
A key represents key items in hamsterdb. Before using a key, it is important to initialize all key fields with zeroes, i.e. with the C library routines memset(3) or bzero(2).
hamsterdb usually uses keys to insert, delete or search for items. However, when using Database Cursors and the function ham_cursor_move, hamsterdb also returns keys. In this case, the pointer to the key data is provided in data. This pointer is only temporary and will be overwritten by subsequent calls to ham_cursor_move using the same Transaction (or, if Transactions are disabled, using the same Database). The pointer will also be invalidated after the Transaction is aborted or committed.
To avoid this, the calling application can allocate the data pointer. In this case, you have to set the flag HAM_KEY_USER_ALLOC. The size parameter will then return the size of the key. It's the responsibility of the caller to make sure that the data parameter is large enough for the key.
The key->data pointer is not threadsafe. For threadsafe access it is recommended to use HAM_KEY_USER_ALLOC or have each thread manage its own Transaction.