<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="libedataserver-EFlag">
<refmeta>
<refentrytitle role="top_of_page" id="libedataserver-EFlag.top_of_page">EFlag</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBEDATASERVER Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>EFlag</refname>
<refpurpose>Simple thread synchronization</refpurpose>
</refnamediv>

<refsynopsisdiv id="libedataserver-EFlag.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
                    <link linkend="EFlag">EFlag</link>;
<link linkend="EFlag">EFlag</link> *             <link linkend="e-flag-new">e_flag_new</link>                          (void);
<link linkend="gboolean">gboolean</link>            <link linkend="e-flag-is-set">e_flag_is_set</link>                       (<link linkend="EFlag">EFlag</link> *flag);
<link linkend="void">void</link>                <link linkend="e-flag-set">e_flag_set</link>                          (<link linkend="EFlag">EFlag</link> *flag);
<link linkend="void">void</link>                <link linkend="e-flag-clear">e_flag_clear</link>                        (<link linkend="EFlag">EFlag</link> *flag);
<link linkend="void">void</link>                <link linkend="e-flag-wait">e_flag_wait</link>                         (<link linkend="EFlag">EFlag</link> *flag);
<link linkend="gboolean">gboolean</link>            <link linkend="e-flag-timed-wait">e_flag_timed_wait</link>                   (<link linkend="EFlag">EFlag</link> *flag,
                                                         <link linkend="GTimeVal">GTimeVal</link> *abs_time);
<link linkend="void">void</link>                <link linkend="e-flag-free">e_flag_free</link>                         (<link linkend="EFlag">EFlag</link> *flag);
</synopsis>
</refsynopsisdiv>









<refsect1 id="libedataserver-EFlag.description" role="desc">
<title role="desc.title">Description</title>
<para>
An <link linkend="EFlag"><type>EFlag</type></link> is a simple thread synchronization mechanism. It implements a
thread-safe flag that can be blocked on.
</para>
</refsect1>

<refsect1 id="libedataserver-EFlag.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="EFlag" role="struct">
<title>EFlag</title>
<indexterm zone="EFlag"><primary sortas="EFlag">EFlag</primary></indexterm><programlisting>typedef struct _EFlag EFlag;</programlisting>
<para>
The <structname>EFlag</structname> struct is an opaque data structure
representing a thread-safe flag.  It should be accessed only by using
the following functions.
</para></refsect2>
<refsect2 id="e-flag-new" role="function">
<title>e_flag_new ()</title>
<indexterm zone="e-flag-new"><primary sortas="e_flag_new">e_flag_new</primary></indexterm><programlisting><link linkend="EFlag">EFlag</link> *             e_flag_new                          (void);</programlisting>
<para>
Creates a new <link linkend="EFlag"><type>EFlag</type></link> object.  It is initially unset.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="EFlag"><type>EFlag</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-flag-is-set" role="function">
<title>e_flag_is_set ()</title>
<indexterm zone="e-flag-is-set"><primary sortas="e_flag_is_set">e_flag_is_set</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            e_flag_is_set                       (<link linkend="EFlag">EFlag</link> *flag);</programlisting>
<para>
Returns the state of <parameter>flag</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>flag</parameter>&#160;:</term>
<listitem><simpara> an <link linkend="EFlag"><type>EFlag</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>flag</parameter> is set
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-flag-set" role="function">
<title>e_flag_set ()</title>
<indexterm zone="e-flag-set"><primary sortas="e_flag_set">e_flag_set</primary></indexterm><programlisting><link linkend="void">void</link>                e_flag_set                          (<link linkend="EFlag">EFlag</link> *flag);</programlisting>
<para>
Sets <parameter>flag</parameter>.  All threads waiting on <parameter>flag</parameter> are woken up.  Threads that
call <link linkend="e-flag-wait"><function>e_flag_wait()</function></link> or <link linkend="e-flag-timed-wait"><function>e_flag_timed_wait()</function></link> once <parameter>flag</parameter> is set will not
block at all.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>flag</parameter>&#160;:</term>
<listitem><simpara> an <link linkend="EFlag"><type>EFlag</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-flag-clear" role="function">
<title>e_flag_clear ()</title>
<indexterm zone="e-flag-clear"><primary sortas="e_flag_clear">e_flag_clear</primary></indexterm><programlisting><link linkend="void">void</link>                e_flag_clear                        (<link linkend="EFlag">EFlag</link> *flag);</programlisting>
<para>
Unsets <parameter>flag</parameter>.  Subsequent calls to <link linkend="e-flag-wait"><function>e_flag_wait()</function></link> or <link linkend="e-flag-timed-wait"><function>e_flag_timed_wait()</function></link>
will block until <parameter>flag</parameter> is set.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>flag</parameter>&#160;:</term>
<listitem><simpara> an <link linkend="EFlag"><type>EFlag</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-flag-wait" role="function">
<title>e_flag_wait ()</title>
<indexterm zone="e-flag-wait"><primary sortas="e_flag_wait">e_flag_wait</primary></indexterm><programlisting><link linkend="void">void</link>                e_flag_wait                         (<link linkend="EFlag">EFlag</link> *flag);</programlisting>
<para>
Blocks until <parameter>flag</parameter> is set.  If <parameter>flag</parameter> is already set, the function returns
immediately.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>flag</parameter>&#160;:</term>
<listitem><simpara> an <link linkend="EFlag"><type>EFlag</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-flag-timed-wait" role="function">
<title>e_flag_timed_wait ()</title>
<indexterm zone="e-flag-timed-wait"><primary sortas="e_flag_timed_wait">e_flag_timed_wait</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            e_flag_timed_wait                   (<link linkend="EFlag">EFlag</link> *flag,
                                                         <link linkend="GTimeVal">GTimeVal</link> *abs_time);</programlisting>
<para>
Blocks until <parameter>flag</parameter> is set, or until the time specified by <parameter>abs_time</parameter>.
If <parameter>flag</parameter> is already set, the function returns immediately.  The return
value indicates the state of <parameter>flag</parameter> after waiting.
</para>
<para>
If <parameter>abs_time</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, <link linkend="e-flag-timed-wait"><function>e_flag_timed_wait()</function></link> acts like <link linkend="e-flag-wait"><function>e_flag_wait()</function></link>.
</para>
<para>
To easily calculate <parameter>abs_time</parameter>, a combination of <link linkend="g-get-current-time"><function>g_get_current_time()</function></link> and
<link linkend="g-time-val-add"><function>g_time_val_add()</function></link> can be used.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>flag</parameter>&#160;:</term>
<listitem><simpara> an <link linkend="EFlag"><type>EFlag</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>abs_time</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTimeVal"><type>GTimeVal</type></link>, determining the final time
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>flag</parameter> is now set
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-flag-free" role="function">
<title>e_flag_free ()</title>
<indexterm zone="e-flag-free"><primary sortas="e_flag_free">e_flag_free</primary></indexterm><programlisting><link linkend="void">void</link>                e_flag_free                         (<link linkend="EFlag">EFlag</link> *flag);</programlisting>
<para>
Destroys <parameter>flag</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>flag</parameter>&#160;:</term>
<listitem><simpara> an <link linkend="EFlag"><type>EFlag</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
