cp_sorted_hash

Section: libcprops - cp_sorted_hash (3)
Updated: SEPTEMBER 2006
Index Return to Main Contents

NAME

cp_sorted_hash_lock, cp_sorted_hash_rdlock, cp_sorted_hash_wrlock, cp_sorted_hash_unlock - acquire / release a lock on an ordered hash table

SYNOPSIS

#include <cprops/sorted_hash.h>

int cp_sorted_hash_lock(cp_sorted_hash *table, int type);
int cp_sorted_hash_rdlock(cp_sorted_hash *table);
int cp_sorted_hash_wrlock(cp_sorted_hash *table);
int cp_sorted_hash_unlock(cp_sorted_hash *table);

DESCRIPTION

cp_sorted_hash_lock locks the table for reading if type is COLLECTION_LOCK_READ or for writing if type is COLLECTION_LOCK_WRITE. The table mode may not have COLLECTION_MODE_NOSYNC set prior to locking. Explicit locking isn't required for single table operations (insertion, retrieval, deletion) which perform locking on their own but rather for transaction-like operations. To prevent other threads from accessing the table while performing a series of mapping insertion, removal and lookup operations, the table must be explicitly locked first. Tree operation functions will not attempt locking if the current thread owns the table lock. This prevents deadlocks but leaves the responsibility for using the correct kind of locking with the application: if there's any possibility the application could change the table structure in the transaction, the table must be write locked. Actions which change the table structure are insertion and deletion, and, in the case of splay tables, lookups as well. The cp_sorted_hash_callback functions however scan the table structure without changing mapping ordering and could be read-locked.

Calls to cp_sorted_hash_lock must be coupled with calls to cp_sorted_hash_unlock after the operation is completed.

cp_sorted_hash_rdlock(table) is a synonym for cp_sorted_hash_lock(table, COLLECTION_LOCK_READ).

is a synonym for cp_sorted_hash_lock(table, COLLECTION_LOCK_WRITE).

RETURN VALUE

cp_sorted_hash_lock, cp_sorted_hash_rdlock and cp_sorted_hash_wrlock return 0 on success, EINVAL if COLLECTION_MODE_NOSYNC is set or -1 if locking fails.
cp_sorted_hash_unlock returns 0 on success or -1 if unlocking fails.