Cancellable Locks: Evolution-Data-Server Reference Manual

## Cancellable Locks Cancellable Locks — locks, which can listen for a GCancellable during lock call |

## Functions

void | e_cancellable_mutex_init ()
void | e_cancellable_mutex_clear ()
gboolean | e_cancellable_mutex_lock ()
void | e_cancellable_mutex_unlock ()
GMutex * | e_cancellable_mutex_get_internal_mutex ()
void | e_cancellable_rec_mutex_init ()
void | e_cancellable_rec_mutex_clear ()
gboolean | e_cancellable_rec_mutex_lock ()
void | e_cancellable_rec_mutex_unlock ()

## Types and Values

struct | ECancellableLocksBase
struct | ECancellableMutex
struct | ECancellableRecMutex

## Description

An ECancellableMutex and an ECancellableRecMutex are similar to GLib's GMutex and GRecMutex, with one exception, their lock function takes also a `GCancellable` instance, thus the waiting for a lock can be cancelled any time.

## Functions

### e_cancellable_mutex_init ()

    void
    e_cancellable_mutex_init (ECancellableMutex *mutex);

`e_cancellable_mutex_init` has been deprecated since version 3.12 and should not be used in newly-written code.

If you think you need this, you're using mutexes wrong.

Initializes `mutex` structure.

#### Parameters

mutex | an ECancellableMutex instance |

Since: 3.8

### e_cancellable_mutex_clear ()

    void
    e_cancellable_mutex_clear (ECancellableMutex *mutex);

`e_cancellable_mutex_clear` has been deprecated since version 3.12 and should not be used in newly-written code.

If you think you need this, you're using mutexes wrong.

Frees memory allocated by `e_cancellable_mutex_init()`.

#### Parameters

mutex | an ECancellableMutex instance |

Since: 3.8

### e_cancellable_mutex_lock ()

    gboolean
    e_cancellable_mutex_lock (ECancellableMutex *mutex,
                              GCancellable *cancellable);

`e_cancellable_mutex_lock` has been deprecated since version 3.12 and should not be used in newly-written code.

If you think you need this, you're using mutexes wrong.

Acquires lock on `mutex` . The returned value indicates whether the lock was acquired, while `FALSE` is returned only either or invalid arguments or the passed in `cancellable` had been cancelled. In case of `NULL` `cancellable` the function blocks like `g_mutex_lock()`.

#### Parameters

mutex | an ECancellableMutex instance |
cancellable | a GCancellable, or `NULL` |

#### Returns

`TRUE`, if lock had been acquired, `FALSE` otherwise

Since: 3.8

### e_cancellable_mutex_unlock ()

    void
    e_cancellable_mutex_unlock (ECancellableMutex *mutex);

`e_cancellable_mutex_unlock` has been deprecated since version 3.12 and should not be used in newly-written code.

If you think you need this, you're using mutexes wrong.

Releases lock previously acquired by `e_cancellable_mutex_lock()`. Behaviour is undefined if this is called on a `mutex` which returned `FALSE` in `e_cancellable_mutex_lock()`.

#### Parameters

mutex | an ECancellableMutex instance |

Since: 3.8

### e_cancellable_mutex_get_internal_mutex ()

    GMutex *
    e_cancellable_mutex_get_internal_mutex
                                   (ECancellableMutex *mutex);

`e_cancellable_mutex_get_internal_mutex` has been deprecated since version 3.12 and should not be used in newly-written code.

If you think you need this, you're using mutexes wrong.

To get internal GMutex. This is meant for cases when a lock is already acquired, and the caller needs to wait for a GCond, in which case the returned GMutex can be used to `g_cond_wait()` or `g_cond_wait_until()`.

#### Parameters

mutex | an ECancellableMutex instance |

#### Returns

Internal GMutex, used in `mutex`

Since: 3.8

### e_cancellable_rec_mutex_init ()

    void
    e_cancellable_rec_mutex_init (ECancellableRecMutex *rec_mutex);

`e_cancellable_rec_mutex_init` has been deprecated since version 3.12 and should not be used in newly-written code.

If you think you need this, you're using mutexes wrong.

Initializes `rec_mutex` structure.

#### Parameters

rec_mutex | an ECancellableRecMutex instance |

Since: 3.8

### e_cancellable_rec_mutex_clear ()

    void
    e_cancellable_rec_mutex_clear (ECancellableRecMutex *rec_mutex);

`e_cancellable_rec_mutex_clear` has been deprecated since version 3.12 and should not be used in newly-written code.

If you think you need this, you're using mutexes wrong.

Frees memory allocated by `e_cancellable_rec_mutex_init()`.

#### Parameters

rec_mutex | an ECancellableRecMutex instance |

Since: 3.8

### e_cancellable_rec_mutex_lock ()

    gboolean
    e_cancellable_rec_mutex_lock (ECancellableRecMutex *rec_mutex,
                                  GCancellable *cancellable);

`e_cancellable_rec_mutex_lock` has been deprecated since version 3.12 and should not be used in newly-written code.

If you think you need this, you're using mutexes wrong.

Acquires lock on `rec_mutex` . The returned value indicates whether the lock was acquired, while `FALSE` is returned only either or invalid arguments or the passed in `cancellable` had been cancelled. In case of `NULL` `cancellable` the function blocks like `g_rec_mutex_lock()`.

#### Parameters

rec_mutex | an ECancellableRecMutex instance |
cancellable | a GCancellable, or `NULL` |

#### Returns

`TRUE`, if lock had been acquired, `FALSE` otherwise

Since: 3.8

### e_cancellable_rec_mutex_unlock ()

    void
    e_cancellable_rec_mutex_unlock (ECancellableRecMutex *rec_mutex);

`e_cancellable_rec_mutex_unlock` has been deprecated since version 3.12 and should not be used in newly-written code.

If you think you need this, you're using mutexes wrong.

Releases lock previously acquired by `e_cancellable_rec_mutex_lock()`. Behaviour is undefined if this is called on a `rec_mutex` which returned `FALSE` in `e_cancellable_rec_mutex_lock()`.

#### Parameters

rec_mutex | an ECancellableRecMutex instance |

Since: 3.8

## Types and Values

### struct ECancellableLocksBase

    struct ECancellableLocksBase {
    	GMutex cond_mutex;
    	GCond cond;
    };

`ECancellableLocksBase` is deprecated and should not be used in newly-written code.

### struct ECancellableMutex

    struct ECancellableMutex {
    	struct _ECancellableLocksBase base;
    	GMutex mutex;
    };

`ECancellableMutex` is deprecated and should not be used in newly-written code.

### struct ECancellableRecMutex

    struct ECancellableRecMutex {
    	struct _ECancellableLocksBase base;
    	GRecMutex rec_mutex;
    };

`ECancellableRecMutex` is deprecated and should not be used in newly-written code.