Connect/disconnect functions

The HAM API library maintains only one connection to the HAM. The library itself is thread-safe, and multiple connections (from different threads) or the same thread are multiplexed on the same single connection to a HAM. The library maintains reference counts.

Here are the basic connect functions:

/* Basic connect functions
   return success (0) or failure (-1, with errno set) */

int ham_connect(unsigned flags);

int ham_disconnect(unsigned flags);

These functions are used to open or close connections to a HAM. The first call to ham_connect*() will open the fd, while subsequent calls will increment the reference count.

Similarly, ham_disconnect() will decrement the count until zero; the call that makes the count zero will close the fd. The functions return -1 on error, and 0 on success. Similarly ham_disconnect*() will decrement the reference count until zero, with the call that makes the count zero closing the fd. The functions return -1 on error with errno set, and 0 on success.

In a multithreaded situation, there will exist only one open connection to a given HAM at any given time, even if multiple threads were to perform ham_connect*()/ham_disconnect*() calls.