session-lock.h File Reference

Functions for creating and managing session locks. More...

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.
typedef int(*	on_unlock_cb) (bool lock_owned, void *context)
	Callback when a session lock has been unlocked.
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.
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.
bool	diffusion_session_lock_is_owned (const DIFFUSION_SESSION_LOCK_T *session_lock)
	Test whether the session lock is still owned.
DIFFUSION_SESSION_LOCK_SCOPE	diffusion_session_lock_get_scope (const DIFFUSION_SESSION_LOCK_T *session_lock)
	The scope of the lock.
void	diffusion_session_lock (SESSION_T *session, const char *lock_name, DIFFUSION_SESSION_LOCK_PARAMS_T params)
	Attempt to acquire a session lock.
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.
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.
DIFFUSION_SESSION_LOCK_T *	diffusion_session_lock_dup (const DIFFUSION_SESSION_LOCK_T *session_lock)
	Duplicate an existing DIFFUSION_SESSION_LOCK_T.
void	diffusion_session_lock_free (DIFFUSION_SESSION_LOCK_T *session_lock)
	Free a memory allocated DIFFUSION_SESSION_LOCK_T

Detailed Description

Functions for creating and managing session locks.

Typedef Documentation

on_lock_acquired_cb

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_lock	The session lock
context	User supplied context passed in from DIFFUSION_SESSION_LOCK_PARAMS_T

Returns

HANDLERS_SUCCESS or HANDLER_FAILURE.

on_unlock_cb

typedef int(* on_unlock_cb) (bool lock_owned, void *context)

Callback when a session lock has been unlocked.

Parameters

lock_owned	A true value indicates this session previously owned the lock and a false value indicates it did not.
context	User supplied context passed in from DIFFUSION_SESSION_LOCK_UNLOCK_PARAMS_T

Returns

HANDLERS_SUCCESS or HANDLER_FAILURE.

Enumeration Type Documentation

DIFFUSION_SESSION_LOCK_SCOPE

enum DIFFUSION_SESSION_LOCK_SCOPE

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

diffusion_session_lock()

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

session	The session handle. If NULL, the function returns immediately.
lock_name	The name of the session lock
params	Parameters describing the session lock request and callbacks handlers which may be invoked in response.

diffusion_session_lock_dup()

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_lock

The session lock to be duplicated

Returns

a duplicate of the DIFFUSION_SESSION_LOCK_T passed into the function

diffusion_session_lock_free()

void diffusion_session_lock_free

(

DIFFUSION_SESSION_LOCK_T *

session_lock

)

Free a memory allocated DIFFUSION_SESSION_LOCK_T

Parameters

session_lock

The session lock to be freed.

diffusion_session_lock_get_name()

char * diffusion_session_lock_get_name

(

const DIFFUSION_SESSION_LOCK_T *

session_lock

)

Returns a copy of a lock's name.

Parameters

session_lock

the session lock to retrieve its name from.

Returns

the session lock's name

diffusion_session_lock_get_scope()

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_lock

The session lock to retrieve its scope from

Returns

the lock scope

diffusion_session_lock_get_sequence()

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_lock

the session lock to retrieve its sequence number from

Returns

a value that identifies the acquisition of this lock

diffusion_session_lock_is_owned()

bool diffusion_session_lock_is_owned

(

const DIFFUSION_SESSION_LOCK_T *

session_lock

)

Test whether the session lock is still owned.

Parameters

session_lock

the session lock to verify if still owned

Returns

true if the session lock is still owned by the session

diffusion_session_lock_unlock()

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

session	The session handle. If NULL, the function returns immediately.
session_lock	The session lock to unlock. If NULL, the function returns immediately.
params	Parameters describing the session lock unlock request and callbacks handlers which may be invoked in response.

diffusion_session_lock_with_scope()

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

session	The session handle. If NULL, the function returns immediately.
lock_name	The name of the session lock
scope	The 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
params	Parameters describing the session lock request and callbacks handlers which may be invoked in response.