// calogHandle.h -- thread-safe, typed integer handle table for calog libraries.
//
// calog library natives (DB, network) are registered INLINE, so they run on whatever
// context thread called them -- many at once. A resource (a connection, a socket) is
// therefore handed to a script as an opaque int64 handle backed by this table, which is
// mutex-guarded and tags every entry with a type so a DB handle can never be used where a
// socket is expected. Handles are monotonic and never reused, so a stale handle from a
// closed resource reliably fails to resolve rather than aliasing a live one.

#ifndef CALOG_HANDLE_H
#define CALOG_HANDLE_H

#include <stdint.h>

typedef struct CalogHandleTableT CalogHandleTableT;

// Invoked for each still-open entry at table destroy, to release the resource.
typedef void (*CalogHandleCloserT)(uint32_t type, void *resource);

// Add returns a positive handle, or 0 on out-of-memory. Get/Remove return the resource
// only when the handle exists AND its type matches; otherwise NULL. Remove also frees the
// slot. Destroy closes every remaining entry through the closer (may be NULL) and frees
// the table.
CalogHandleTableT *calogHandleTableCreate(void);
void               calogHandleTableDestroy(CalogHandleTableT *table, CalogHandleCloserT closer);
int64_t            calogHandleAdd(CalogHandleTableT *table, uint32_t type, void *resource);
void              *calogHandleGet(CalogHandleTableT *table, int64_t handle, uint32_t type);
void              *calogHandleRemove(CalogHandleTableT *table, int64_t handle, uint32_t type);

// Number of live entries of the given type currently in the table.
int32_t            calogHandleCount(CalogHandleTableT *table, uint32_t type);

#endif