## EFlag EFlag — Simple thread synchronization |

## Synopsis

                        EFlag;
    EFlag *             e_flag_new                          (void);
    gboolean            e_flag_is_set                       (EFlag *flag);
    void                e_flag_set                          (EFlag *flag);
    void                e_flag_clear                        (EFlag *flag);
    void                e_flag_wait                         (EFlag *flag);
    gboolean            e_flag_timed_wait                   (EFlag *flag,
                                                             GTimeVal *abs_time);
    void                e_flag_free                         (EFlag *flag);

## Description

An EFlag is a simple thread synchronization mechanism. It implements a thread-safe flag that can be blocked on.

## Details

### EFlag

    typedef struct _EFlag EFlag;

The EFlag struct is an opaque data structure representing a thread-safe flag. It should be accessed only by using the following functions.

### e_flag_new ()

    EFlag *             e_flag_new                          (void);

Creates a new EFlag object. It is initially unset.

Returns : | a new EFlag

### e_flag_is_set ()

    gboolean            e_flag_is_set                       (EFlag *flag);

Returns the state of `flag`.

`flag` : | an EFlag
Returns : | `TRUE` if `flag` is set

### e_flag_set ()

    void                e_flag_set                          (EFlag *flag);

Sets `flag`. All threads waiting on `flag` are woken up. Threads that call `e_flag_wait()` or `e_flag_timed_wait()` once `flag` is set will not block at all.

`flag` : | an EFlag

### e_flag_clear ()

    void                e_flag_clear                        (EFlag *flag);

Unsets `flag`. Subsequent calls to `e_flag_wait()` or `e_flag_timed_wait()` will block until `flag` is set.

`flag` : | an EFlag

### e_flag_wait ()

    void                e_flag_wait                         (EFlag *flag);

Blocks until `flag` is set. If `flag` is already set, the function returns immediately.

`flag` : | an EFlag

### e_flag_timed_wait ()

    gboolean            e_flag_timed_wait                   (EFlag *flag,
                                                             GTimeVal *abs_time);

Blocks until `flag` is set, or until the time specified by `abs_time`. If `flag` is already set, the function returns immediately. The return value indicates the state of `flag` after waiting.

If `abs_time` is `NULL`, `e_flag_timed_wait()` acts like `e_flag_wait()`.

To easily calculate `abs_time`, a combination of `g_get_current_time()` and `g_time_val_add()` can be used.

`flag` : | an EFlag
`abs_time` : | a GTimeVal, determining the final time
Returns : | `TRUE` if `flag` is now set

### e_flag_free ()

    void                e_flag_free                         (EFlag *flag);

Destroys `flag`.

`flag` : | an EFlag