gclosure.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="gobject-Closures">
<refmeta>
<refentrytitle>Closures</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GOBJECT Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Closures</refname><refpurpose></refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gobject.h&gt;


#define     <link linkend="G-CLOSURE-NEEDS-MARSHAL-CAPS">G_CLOSURE_NEEDS_MARSHAL</link>         (closure)
#define     <link linkend="G-CLOSURE-N-NOTIFIERS-CAPS">G_CLOSURE_N_NOTIFIERS</link>           (cl)
#define     <link linkend="G-CCLOSURE-SWAP-DATA-CAPS">G_CCLOSURE_SWAP_DATA</link>            (cclosure)
#define     <link linkend="G-CALLBACK-CAPS">G_CALLBACK</link>                      (f)
void        (<link linkend="GCallback">*GCallback</link>)                    (void);
struct      <link linkend="GClosure">GClosure</link>;
#define     <link linkend="G-TYPE-CLOSURE-CAPS">G_TYPE_CLOSURE</link>
struct      <link linkend="GCClosure">GCClosure</link>;
void        (<link linkend="GClosureMarshal">*GClosureMarshal</link>)              (<link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="GValue">GValue</link> *return_value,
                                             <link linkend="guint">guint</link> n_param_values,
                                             const <link linkend="GValue">GValue</link> *param_values,
                                             <link linkend="gpointer">gpointer</link> invocation_hint,
                                             <link linkend="gpointer">gpointer</link> marshal_data);
void        (<link linkend="GClosureNotify">*GClosureNotify</link>)               (<link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GClosure">GClosure</link> *closure);
struct      <link linkend="GClosureNotifyData">GClosureNotifyData</link>;
<link linkend="GClosure">GClosure</link>*   <link linkend="g-cclosure-new">g_cclosure_new</link>                  (<link linkend="GCallback">GCallback</link> callback_func,
                                             <link linkend="gpointer">gpointer</link> user_data,
                                             <link linkend="GClosureNotify">GClosureNotify</link> destroy_data);
<link linkend="GClosure">GClosure</link>*   <link linkend="g-cclosure-new-swap">g_cclosure_new_swap</link>             (<link linkend="GCallback">GCallback</link> callback_func,
                                             <link linkend="gpointer">gpointer</link> user_data,
                                             <link linkend="GClosureNotify">GClosureNotify</link> destroy_data);
<link linkend="GClosure">GClosure</link>*   <link linkend="g-cclosure-new-object">g_cclosure_new_object</link>           (<link linkend="GCallback">GCallback</link> callback_func,
                                             <link linkend="GObject">GObject</link> *object);
<link linkend="GClosure">GClosure</link>*   <link linkend="g-cclosure-new-object-swap">g_cclosure_new_object_swap</link>      (<link linkend="GCallback">GCallback</link> callback_func,
                                             <link linkend="GObject">GObject</link> *object);
<link linkend="GClosure">GClosure</link>*   <link linkend="g-closure-new-object">g_closure_new_object</link>            (<link linkend="guint">guint</link> sizeof_closure,
                                             <link linkend="GObject">GObject</link> *object);
<link linkend="GClosure">GClosure</link>*   <link linkend="g-closure-ref">g_closure_ref</link>                   (<link linkend="GClosure">GClosure</link> *closure);
void        <link linkend="g-closure-sink">g_closure_sink</link>                  (<link linkend="GClosure">GClosure</link> *closure);
void        <link linkend="g-closure-unref">g_closure_unref</link>                 (<link linkend="GClosure">GClosure</link> *closure);
void        <link linkend="g-closure-invoke">g_closure_invoke</link>                (<link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="GValue">GValue</link> *return_value,
                                             <link linkend="guint">guint</link> n_param_values,
                                             const <link linkend="GValue">GValue</link> *param_values,
                                             <link linkend="gpointer">gpointer</link> invocation_hint);
void        <link linkend="g-closure-invalidate">g_closure_invalidate</link>            (<link linkend="GClosure">GClosure</link> *closure);
void        <link linkend="g-closure-add-finalize-notifier">g_closure_add_finalize_notifier</link> (<link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gpointer">gpointer</link> notify_data,
                                             <link linkend="GClosureNotify">GClosureNotify</link> notify_func);
void        <link linkend="g-closure-add-invalidate-notifier">g_closure_add_invalidate_notifier</link>
                                            (<link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gpointer">gpointer</link> notify_data,
                                             <link linkend="GClosureNotify">GClosureNotify</link> notify_func);
void        <link linkend="g-closure-remove-finalize-notifier">g_closure_remove_finalize_notifier</link>
                                            (<link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gpointer">gpointer</link> notify_data,
                                             <link linkend="GClosureNotify">GClosureNotify</link> notify_func);
void        <link linkend="g-closure-remove-invalidate-notifier">g_closure_remove_invalidate_notifier</link>
                                            (<link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gpointer">gpointer</link> notify_data,
                                             <link linkend="GClosureNotify">GClosureNotify</link> notify_func);
<link linkend="GClosure">GClosure</link>*   <link linkend="g-closure-new-simple">g_closure_new_simple</link>            (<link linkend="guint">guint</link> sizeof_closure,
                                             <link linkend="gpointer">gpointer</link> data);
void        <link linkend="g-closure-set-marshal">g_closure_set_marshal</link>           (<link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="GClosureMarshal">GClosureMarshal</link> marshal);
void        <link linkend="g-closure-add-marshal-guards">g_closure_add_marshal_guards</link>    (<link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gpointer">gpointer</link> pre_marshal_data,
                                             <link linkend="GClosureNotify">GClosureNotify</link> pre_marshal_notify,
                                             <link linkend="gpointer">gpointer</link> post_marshal_data,
                                             <link linkend="GClosureNotify">GClosureNotify</link> post_marshal_notify);
void        <link linkend="g-closure-set-meta-marshal">g_closure_set_meta_marshal</link>      (<link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gpointer">gpointer</link> marshal_data,
                                             <link linkend="GClosureMarshal">GClosureMarshal</link> meta_marshal);
void        <link linkend="g-source-set-closure">g_source_set_closure</link>            (<link linkend="GSource">GSource</link> *source,
                                             <link linkend="GClosure">GClosure</link> *closure);
#define     <link linkend="G-TYPE-IO-CHANNEL-CAPS">G_TYPE_IO_CHANNEL</link>
#define     <link linkend="G-TYPE-IO-CONDITION-CAPS">G_TYPE_IO_CONDITION</link>

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="G-CLOSURE-NEEDS-MARSHAL-CAPS">G_CLOSURE_NEEDS_MARSHAL()</title>
<programlisting>#define	G_CLOSURE_NEEDS_MARSHAL(closure) (((GClosure*) (closure))-&gt;marshal == NULL)
</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>closure</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-CLOSURE-N-NOTIFIERS-CAPS">G_CLOSURE_N_NOTIFIERS()</title>
<programlisting>#define     G_CLOSURE_N_NOTIFIERS(cl)</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>cl</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-CCLOSURE-SWAP-DATA-CAPS">G_CCLOSURE_SWAP_DATA()</title>
<programlisting>#define	G_CCLOSURE_SWAP_DATA(cclosure)	 (((GClosure*) (closure))-&gt;derivative_flag)
</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>cclosure</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-CALLBACK-CAPS">G_CALLBACK()</title>
<programlisting>#define	G_CALLBACK(f)			 ((GCallback) (f))
</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>f</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GCallback">GCallback ()</title>
<programlisting>void        (*GCallback)                    (void);</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="GClosure">struct GClosure</title>
<programlisting>struct GClosure
{
  /*&lt; private &gt;*/	guint	 ref_count : 15;
  /*&lt; private &gt;*/	guint	 meta_marshal : 1;
  /*&lt; private &gt;*/	guint	 n_guards : 1;
  /*&lt; private &gt;*/	guint	 n_fnotifiers : 2;	/* finalization notifiers */
  /*&lt; private &gt;*/	guint	 n_inotifiers : 8;	/* invalidation notifiers */
  /*&lt; private &gt;*/	guint	 in_inotify : 1;
  /*&lt; private &gt;*/	guint	 floating : 1;
  /*&lt; protected &gt;*/	guint	 derivative_flag : 1;
  /*&lt; public &gt;*/	guint	 in_marshal : 1;
  /*&lt; public &gt;*/	guint	 is_invalid : 1;

  /*&lt; private &gt;*/	void   (*marshal)  (GClosure       *closure,
					    GValue /*out*/ *return_value,
					    guint           n_param_values,
					    const GValue   *param_values,
					    gpointer        invocation_hint,
					    gpointer	    marshal_data);
  /*&lt; protected &gt;*/	gpointer data;

  /*&lt; private &gt;*/	GClosureNotifyData *notifiers;

  /* invariants/constrains:
   * - -&gt;marshal and -&gt;data are _invalid_ as soon as -&gt;is_invalid==TRUE
   * - invocation of all inotifiers occours prior to fnotifiers
   * - order of inotifiers is random
   *   inotifiers may _not_ free/invalidate parameter values (e.g. -&gt;data)
   * - order of fnotifiers is random
   * - each notifier may only be removed before or during its invocation
   * - reference counting may only happen prior to fnotify invocation
   *   (in that sense, fnotifiers are really finalization handlers)
   */
};
</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="guint">guint</link> <structfield>in_marshal</structfield> : 1</entry>
<entry>
</entry>
</row>
<row>
<entry><link linkend="guint">guint</link> <structfield>is_invalid</structfield> : 1</entry>
<entry>Indicates whether the closure has been invalidated by <link linkend="g-closure-invalidate">g_closure_invalidate</link>()

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-TYPE-CLOSURE-CAPS">G_TYPE_CLOSURE</title>
<programlisting>#define	G_TYPE_CLOSURE		(g_closure_get_type ())
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="GCClosure">struct GCClosure</title>
<programlisting>struct GCClosure
{
  GClosure	closure;
  gpointer	callback;
};
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="GClosureMarshal">GClosureMarshal ()</title>
<programlisting>void        (*GClosureMarshal)              (<link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="GValue">GValue</link> *return_value,
                                             <link linkend="guint">guint</link> n_param_values,
                                             const <link linkend="GValue">GValue</link> *param_values,
                                             <link linkend="gpointer">gpointer</link> invocation_hint,
                                             <link linkend="gpointer">gpointer</link> marshal_data);</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>closure</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>return_value</parameter>&nbsp;:</entry>
<entry>