LockServiceLock

LockServiceLock — a GObject representing a lock-service lock

Synopsis

#define             LOCK_SERVICE_ERROR
enum                LockServiceError;

                    LockServiceLock;
                    LockServiceLockClass;

LockServiceLock *   lock_service_lock_construct         (GType type,
                                                         const gchar *name);
LockServiceLock *   lock_service_lock_new               (const gchar *name);

gboolean            lock_service_lock_begin             (LockServiceLock *lock,
                                                         const gchar *request,
                                                         gchar **reply,
                                                         GError **error);
void                lock_service_lock_begin_async       (LockServiceLock *lock,
                                                         const gchar *request,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            lock_service_lock_begin_finish      (LockServiceLock *lock,
                                                         GAsyncResult *result,
                                                         gchar **reply,
                                                         GError **error);

void                lock_service_lock_end               (LockServiceLock *lock);

gchar *             lock_service_lock_request           (LockServiceLock *lock,
                                                         const gchar *request);
void                lock_service_lock_request_async     (LockServiceLock *lock,
                                                         const gchar *request,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gchar *             lock_service_lock_request_finish    (LockServiceLock *lock,
                                                         GAsyncResult *result);

Object Hierarchy

  GObject
   +----LockServiceLock

Properties

  "name"                     gchar*                : Read / Write / Construct Only

Description

Details

LOCK_SERVICE_ERROR

#define LOCK_SERVICE_ERROR                                  lock_service_error_quark ()

Error domain for LockServiceLock operations. Errors in this domain will be from the LockServiceError enumeration. See GError for information on error domains.


enum LockServiceError

typedef enum
{
  LOCK_SERVICE_ERROR_FAILED
} LockServiceError;

Error codes for problems that can occur with LockServiceLock operations.

LOCK_SERVICE_ERROR_FAILED

a generic error. Currently, all errors are generic errors.

LockServiceLock

typedef struct _LockServiceLock LockServiceLock;

This is an opaque structure; it may not be accessed directly.


LockServiceLockClass

typedef struct {
  GObjectClass parent_class;

  gchar * (*request)        (LockServiceLock     *lock,
                             const gchar         *request);
  void    (*request_async)  (LockServiceLock     *lock,
                             const gchar         *request,
                             GAsyncReadyCallback  callback,
                             gpointer             user_data);
  gchar * (*request_finish) (LockServiceLock     *lock,
                             GAsyncResult        *result);
} LockServiceLockClass;

The class structure for LockServiceLock.

GObjectClass parent_class;

request ()

virtual function pointer for lock_service_lock_request(). The default implementation ignores the request and returns the empty string. Overriding the default implementation of request_async means that this function will never be called unless you explicitly call it.

request_async ()

virtual function pointer for lock_service_lock_request_async(). The default implementation of this function calls the non-asynchronous version, puts the result into a GSimpleAsyncResult and dispatches it in an idle handler on the default mainloop.

request_finish ()

virtual function pointer for lock_service_lock_request_finish(). The default implementation of this function expects a GSimpleAsyncResult with the source_tag set to lock_service_lock_request_async() and the payload set to a weak pointer to the reply string (ie: the string will be duplicated before it is returned).

lock_service_lock_construct ()

LockServiceLock *   lock_service_lock_construct         (GType type,
                                                         const gchar *name);

Constructs a LockServiceLock, or subclass.

This is the Dova-style (ie: Vala-friendly) construction function. See lock_service_lock_new() for normal uses.

type :

LOCK_SERVICE_TYPE_LOCK, or a subclass GType

name :

the name of the lock

returns :

a new LockServiceLock, or subclass

lock_service_lock_new ()

LockServiceLock *   lock_service_lock_new               (const gchar *name);

Creates a new LockServiceLock with the unique name of name.

A lock of a given name can only be held once by a given user on a given machine. Two users on the same machine can hold locks of the same name. A user may hold locks of two different names. A user may hold a lock of the same name on two different machines.

name :

the name of the lock

returns :

a new LockServiceLock

lock_service_lock_begin ()

gboolean            lock_service_lock_begin             (LockServiceLock *lock,
                                                         const gchar *request,
                                                         gchar **reply,
                                                         GError **error);

Acquire the lock or send a message to the existing owner.

The lock is acquired if and only if a lock of the same name is not being held by the same user on the same system.

It is an error to call this function if lock is already holding the lock.

In the event that the lock is acquired (ie: we now hold the lock), reply will be set to NULL, TRUE will be returned and the reference count of lock will be increased by one. The reference count will drop again when lock_service_lock_end() is called.

In the event that the lock is already held then request (which must be non-NULL) will be sent to the holder. The holder's reply (which will also be non-NULL) is placed in reply and TRUE is returned. The reference count will not be increased.

In the event of an error, error will be set accordingly and FALSE returned.

While the lock is held, lock may receive requests. These requests result in calls being made to lock_service_lock_request_async(). For non-trivial uses, you will want to override this virtual function. See LockServiceLockClass.

lock_service_lock_request() is not called for the request given to this function. If you want that, then check for reply being set to NULL, then invoke the function yourself.

lock :

a LockServiceLock

request :

the request string, non-NULL

reply :

a pointer to the reply from the service, or NULL

error :

a pointer to a NULL GError, or NULL

lock_service_lock_begin_async ()

void                lock_service_lock_begin_async       (LockServiceLock *lock,
                                                         const gchar *request,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

This is the first half of the asynchronous variant of lock_service_lock_begin(). The result of this function should be collected by calling lock_service_lock_begin_finish() from callback.

No other calls may be made on lock while the operation is in progress.

lock :

a LockServiceLock

request :

the request string, non-NULL

callback :

a GAsyncReadyCallback

user_data :

user data for callback

lock_service_lock_begin_finish ()

gboolean            lock_service_lock_begin_finish      (LockServiceLock *lock,
                                                         GAsyncResult *result,
                                                         gchar **reply,
                                                         GError **error);

This is the second half of the asynchronous variant of lock_service_lock_begin(). This function should be called from the callback given to lock_service_lock_begin_async().

lock :

the LockServiceLock passed to the ready callback

result :

the GAsyncResult passed to the ready callback

reply :

a pointer to the reply from the service, or NULL

error :

a pointer to a NULL GError, or NULL

lock_service_lock_end ()

void                lock_service_lock_end               (LockServiceLock *lock);

Releases the lock. The reference count of lock is decreased.

It is an error to call this function if lock is not holding the lock.

lock :

a LockServiceLock

lock_service_lock_request ()

gchar *             lock_service_lock_request           (LockServiceLock *lock,
                                                         const gchar *request);

Makes a request to lock.

The exact nature of what this call does depends on how the virtual functions in the LockServiceLockClass structure are overridden.

It is appropriate to call g_free() on the return value.

lock :

a LockServiceLock

request :

the request string, non-NULL

returns :

a newly-allocated string

lock_service_lock_request_async ()

void                lock_service_lock_request_async     (LockServiceLock *lock,
                                                         const gchar *request,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

This is the first half of the asynchronous variant of lock_service_lock_request(). The result of this function should be collected by calling lock_service_lock_request_finish() from callback.

No other calls may be made on lock while the operation is in progress.

lock :

a LockServiceLock

request :

the request string, non-NULL

callback :

a GAsyncReadyCallback

user_data :

user data for callback

lock_service_lock_request_finish ()

gchar *             lock_service_lock_request_finish    (LockServiceLock *lock,
                                                         GAsyncResult *result);

This is the second half of the asynchronous variant of lock_service_lock_request(). This function should be called from the callback given to lock_service_lock_request_async().

lock :

a LockServiceLock

result :

the GAsyncResult passed to the ready callback

Property Details

The "name" property

  "name"                     gchar*                : Read / Write / Construct Only

the unique name of the lock to acquire.

Default value: NULL