Diffusion C API  6.7.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
session-lock.h File Reference

Data Structures

struct  diffusion_session_lock_params_s
 Structure describing a session lock request. More...
 
struct  diffusion_session_lock_unlock_params_s
 Structure describing a session lock unlock request. More...
 

Typedefs

typedef struct
DIFFUSION_SESSION_LOCK_T 
DIFFUSION_SESSION_LOCK_T
 An opaque session lock struct.
 
typedef int(* on_lock_acquired_cb )(const DIFFUSION_SESSION_LOCK_T *session_lock, void *context)
 Callback when a session lock has been acquired. More...
 
typedef int(* on_unlock_cb )(bool lock_owned, void *context)
 Callback when a session lock has been unlocked. More...
 
typedef struct
diffusion_session_lock_params_s 
DIFFUSION_SESSION_LOCK_PARAMS_T
 Structure describing a session lock request.
 
typedef struct
diffusion_session_lock_unlock_params_s 
DIFFUSION_SESSION_LOCK_UNLOCK_PARAMS_T
 Structure describing a session lock unlock request.
 

Enumerations

enum  DIFFUSION_SESSION_LOCK_SCOPE { UNLOCK_ON_CONNECTION_LOSS, UNLOCK_ON_SESSION_LOSS }
 

Functions

char * diffusion_session_lock_get_name (const DIFFUSION_SESSION_LOCK_T *session_lock)
 Returns a copy of a lock's name. More...
 
long diffusion_session_lock_get_sequence (const DIFFUSION_SESSION_LOCK_T *session_lock)
 A value that identifying the acquisition of the lock with the given name. More...
 
bool diffusion_session_lock_is_owned (const DIFFUSION_SESSION_LOCK_T *session_lock)
 Test whether the session lock is still owned. More...
 
DIFFUSION_SESSION_LOCK_SCOPE diffusion_session_lock_get_scope (const DIFFUSION_SESSION_LOCK_T *session_lock)
 The scope of the lock. More...
 
void diffusion_session_lock (SESSION_T *session, const char *lock_name, DIFFUSION_SESSION_LOCK_PARAMS_T params)
 Attempt to acquire a session lock. More...
 
void diffusion_session_lock_with_scope (SESSION_T *session, const char *lock_name, DIFFUSION_SESSION_LOCK_SCOPE scope, DIFFUSION_SESSION_LOCK_PARAMS_T params)
 Variant of diffusion_session_lock that provides control over when a lock will be released. More...
 
void diffusion_session_lock_unlock (SESSION_T *session, const DIFFUSION_SESSION_LOCK_T *session_lock, DIFFUSION_SESSION_LOCK_UNLOCK_PARAMS_T params)
 Release a session lock, if owned. More...
 
DIFFUSION_SESSION_LOCK_Tdiffusion_session_lock_dup (const DIFFUSION_SESSION_LOCK_T *session_lock)
 Duplicate an existing DIFFUSION_SESSION_LOCK_T. More...
 
void diffusion_session_lock_free (DIFFUSION_SESSION_LOCK_T *session_lock)
 Free a memory allocated DIFFUSION_SESSION_LOCK_T More...
 

Typedef Documentation

typedef int(* on_lock_acquired_cb)(const DIFFUSION_SESSION_LOCK_T *session_lock, void *context)

Callback when a session lock has been acquired.

Parameters
session_lockThe session lock
contextUser supplied context passed in from DIFFUSION_SESSION_LOCK_PARAMS_T
Returns
HANDLERS_SUCCESS or HANDLER_FAILURE.
typedef int(* on_unlock_cb)(bool lock_owned, void *context)

Callback when a session lock has been unlocked.

Parameters
lock_ownedA true value indicates this session previously owned the lock and a false value indicates it did not.
contextUser supplied context passed in from DIFFUSION_SESSION_LOCK_UNLOCK_PARAMS_T
Returns
HANDLERS_SUCCESS or HANDLER_FAILURE.

Enumeration Type Documentation

Enumerator
UNLOCK_ON_CONNECTION_LOSS 

The lock will be released when the acquiring session loses its current connection to the server.

UNLOCK_ON_SESSION_LOSS 

The lock will be released when the acquiring session is closed.

Function Documentation

void diffusion_session_lock ( SESSION_T session,
const char *  lock_name,
DIFFUSION_SESSION_LOCK_PARAMS_T  params 
)

Attempt to acquire a session lock.

Acquiring the lock can take an arbitrarily long time if other sessions are competing for the lock. The server will retain the session's request for the lock until it is assigned to the session or the session is closed

A session can call this method multiple times. If the lock is acquired, all calls will complete successfully with equal SessionLocks.

A session that acquires a lock will remain its owner until it is unlocked with diffusion_session_lock_unlock or the session closes. The diffusion_session_lock_with_scope variant of this method takes a scope parameter that provides the further option of releasing the lock when the session loses its connection to the server.

To allow fine-grained access control, lock names are interpreted as path names, controlled with the ACQUIRE_LOCK path permission. This allows permission to be granted to a session to acquire the lock update-topic/a while preventing the session from acquiring the lock update-topic/b, for example.

Parameters
sessionThe session handle. If NULL, the function returns immediately.
lock_nameThe name of the session lock
paramsParameters describing the session lock request and callbacks handlers which may be invoked in response.
DIFFUSION_SESSION_LOCK_T* diffusion_session_lock_dup ( const DIFFUSION_SESSION_LOCK_T session_lock)

Duplicate an existing DIFFUSION_SESSION_LOCK_T.

diffusion_session_lock_free should be called on the pointer when no longer needed.

Parameters
session_lockThe session lock to be duplicated
Returns
a duplicate of the DIFFUSION_SESSION_LOCK_T passed into the function
void diffusion_session_lock_free ( DIFFUSION_SESSION_LOCK_T session_lock)

Free a memory allocated DIFFUSION_SESSION_LOCK_T

Parameters
session_lockThe session lock to be freed.
char* diffusion_session_lock_get_name ( const DIFFUSION_SESSION_LOCK_T session_lock)

Returns a copy of a lock's name.

Parameters
session_lockthe session lock to retrieve its name from.
Returns
the session lock's name
DIFFUSION_SESSION_LOCK_SCOPE diffusion_session_lock_get_scope ( const DIFFUSION_SESSION_LOCK_T session_lock)

The scope of the lock.

The scope determines when the lock will be released automatically.

If a session makes multiple diffusion_session_lock_with_scope requests for a lock using different scopes, and the server assigns the lock to the session fulfilling the requests, the lock will be given the weakest scope UNLOCK_ON_CONNECTION_LOSS. Consequently, an individual request can complete with a lock that has a different scope to that requested.

Parameters
session_lockThe session lock to retrieve its scope from
Returns
the lock scope
long diffusion_session_lock_get_sequence ( const DIFFUSION_SESSION_LOCK_T session_lock)

A value that identifying the acquisition of the lock with the given name.

Session locks that are acquired later are guaranteed to have bigger sequence values, allowing the sequence number to be used as a fencing token.

Parameters
session_lockthe session lock to retrieve its sequence number from
Returns
a value that identifies the acquisition of this lock
bool diffusion_session_lock_is_owned ( const DIFFUSION_SESSION_LOCK_T session_lock)

Test whether the session lock is still owned.

Parameters
session_lockthe session lock to verify if still owned
Returns
true if the session lock is still owned by the session
void diffusion_session_lock_unlock ( SESSION_T session,
const DIFFUSION_SESSION_LOCK_T session_lock,
DIFFUSION_SESSION_LOCK_UNLOCK_PARAMS_T  params 
)

Release a session lock, if owned.

Parameters
sessionThe session handle. If NULL, the function returns immediately.
session_lockThe session lock to unlock. If NULL, the function returns immediately.
paramsParameters describing the session lock unlock request and callbacks handlers which may be invoked in response.
void diffusion_session_lock_with_scope ( SESSION_T session,
const char *  lock_name,
DIFFUSION_SESSION_LOCK_SCOPE  scope,
DIFFUSION_SESSION_LOCK_PARAMS_T  params 
)

Variant of diffusion_session_lock that provides control over when a lock will be released.

If called with UNLOCK_ON_SESSION_LOSS this method behaves exactly like diffusion_session_lock.

If called with UNLOCK_ON_CONNECTION_LOSS, any lock that are returned will be unlocked if the session loses its connection to the server. This is useful to allow another session to take ownership of the lock while this session is reconnecting.

Parameters
sessionThe session handle. If NULL, the function returns immediately.
lock_nameThe name of the session lock
scopeThe preferred scope. The scope of a lock controls when it will be released automatically. If a session makes multiple requests for a lock using different scopes, and the server assigns the lock to the session fulfilling the requests, the lock will be given the weakest scope UNLOCK_ON_CONNECTION_LOSS
paramsParameters describing the session lock request and callbacks handlers which may be invoked in response.