Add a generic libffi based marshaller to libgobject
[platform/upstream/glib.git] / gobject / gclosure.h
1 /* GObject - GLib Type, Object, Parameter and Signal Library
2  * Copyright (C) 2000-2001 Red Hat, Inc.
3  * Copyright (C) 2005 Imendio AB
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General
16  * Public License along with this library; if not, write to the
17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18  * Boston, MA 02111-1307, USA.
19  */
20 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
21 #error "Only <glib-object.h> can be included directly."
22 #endif
23
24 #ifndef __G_CLOSURE_H__
25 #define __G_CLOSURE_H__
26
27 #include        <gobject/gtype.h>
28
29 G_BEGIN_DECLS
30
31 /* --- defines --- */
32 /**
33  * G_CLOSURE_NEEDS_MARSHAL:
34  * @closure: a #GClosure
35  * 
36  * Check if the closure still needs a marshaller. See g_closure_set_marshal().
37  *
38  * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on 
39  * @closure.
40  */
41 #define G_CLOSURE_NEEDS_MARSHAL(closure) (((GClosure*) (closure))->marshal == NULL)
42 /**
43  * G_CLOSURE_N_NOTIFIERS:
44  * @cl: a #GClosure
45  * 
46  * Get the total number of notifiers connected with the closure @cl. 
47  * The count includes the meta marshaller, the finalize and invalidate notifiers 
48  * and the marshal guards. Note that each guard counts as two notifiers. 
49  * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(),
50  * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards().
51  *
52  * Returns: number of notifiers
53  */
54 #define G_CLOSURE_N_NOTIFIERS(cl)        ((cl)->meta_marshal + ((cl)->n_guards << 1L) + \
55                                           (cl)->n_fnotifiers + (cl)->n_inotifiers)
56 /**
57  * G_CCLOSURE_SWAP_DATA:
58  * @cclosure: a #GCClosure
59  * 
60  * Checks whether the user data of the #GCClosure should be passed as the
61  * first parameter to the callback. See g_cclosure_new_swap().
62  *
63  * Returns: %TRUE if data has to be swapped.
64  */
65 #define G_CCLOSURE_SWAP_DATA(cclosure)   (((GClosure*) (cclosure))->derivative_flag)
66 /**
67  * G_CALLBACK:
68  * @f: a function pointer.
69  * 
70  * Cast a function pointer to a #GCallback.
71  */
72 #define G_CALLBACK(f)                    ((GCallback) (f))
73
74
75 /* -- typedefs --- */
76 typedef struct _GClosure                 GClosure;
77 typedef struct _GClosureNotifyData       GClosureNotifyData;
78
79 /**
80  * GCallback:
81  * 
82  * The type used for callback functions in structure definitions and function 
83  * signatures. This doesn't mean that all callback functions must take no 
84  * parameters and return void. The required signature of a callback function 
85  * is determined by the context in which is used (e.g. the signal to which it 
86  * is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. 
87  */
88 typedef void  (*GCallback)              (void);
89 /**
90  * GClosureNotify:
91  * @data: data specified when registering the notification callback
92  * @closure: the #GClosure on which the notification is emitted
93  * 
94  * The type used for the various notification callbacks which can be registered
95  * on closures.
96  */
97 typedef void  (*GClosureNotify)         (gpointer        data,
98                                          GClosure       *closure);
99 /**
100  * GClosureMarshal:
101  * @closure: the #GClosure to which the marshaller belongs
102  * @return_value: a #GValue to store the return value. May be %NULL if the
103  *  callback of @closure doesn't return a value.
104  * @n_param_values: the length of the @param_values array
105  * @param_values: an array of #GValue<!-- -->s holding the arguments on
106  *  which to invoke the callback of @closure
107  * @invocation_hint: the invocation hint given as the last argument
108  *  to g_closure_invoke()
109  * @marshal_data: additional data specified when registering the marshaller,
110  *  see g_closure_set_marshal() and g_closure_set_meta_marshal()
111  * 
112  * The type used for marshaller functions.
113  */
114 typedef void  (*GClosureMarshal)        (GClosure       *closure,
115                                          GValue         *return_value,
116                                          guint           n_param_values,
117                                          const GValue   *param_values,
118                                          gpointer        invocation_hint,
119                                          gpointer        marshal_data);
120 /**
121  * GCClosure:
122  * @closure: the #GClosure
123  * @callback: the callback function
124  * 
125  * A #GCClosure is a specialization of #GClosure for C function callbacks.
126  */
127 typedef struct _GCClosure                GCClosure;
128
129
130 /* --- structures --- */
131 struct _GClosureNotifyData
132 {
133   gpointer       data;
134   GClosureNotify notify;
135 };
136 /**
137  * GClosure:
138  * @in_marshal: Indicates whether the closure is currently being invoked with 
139  *  g_closure_invoke()
140  * @is_invalid: Indicates whether the closure has been invalidated by 
141  *  g_closure_invalidate()
142  * 
143  * A #GClosure represents a callback supplied by the programmer.
144  */
145 struct _GClosure
146 {
147   /*< private >*/
148   volatile              guint    ref_count : 15;
149   volatile              guint    meta_marshal : 1;
150   volatile              guint    n_guards : 1;
151   volatile              guint    n_fnotifiers : 2;      /* finalization notifiers */
152   volatile              guint    n_inotifiers : 8;      /* invalidation notifiers */
153   volatile              guint    in_inotify : 1;
154   volatile              guint    floating : 1;
155   /*< protected >*/
156   volatile              guint    derivative_flag : 1;
157   /*< public >*/
158   volatile              guint    in_marshal : 1;
159   volatile              guint    is_invalid : 1;
160
161   /*< private >*/       void   (*marshal)  (GClosure       *closure,
162                                             GValue /*out*/ *return_value,
163                                             guint           n_param_values,
164                                             const GValue   *param_values,
165                                             gpointer        invocation_hint,
166                                             gpointer        marshal_data);
167   /*< protected >*/     gpointer data;
168
169   /*< private >*/       GClosureNotifyData *notifiers;
170
171   /* invariants/constrains:
172    * - ->marshal and ->data are _invalid_ as soon as ->is_invalid==TRUE
173    * - invocation of all inotifiers occours prior to fnotifiers
174    * - order of inotifiers is random
175    *   inotifiers may _not_ free/invalidate parameter values (e.g. ->data)
176    * - order of fnotifiers is random
177    * - each notifier may only be removed before or during its invocation
178    * - reference counting may only happen prior to fnotify invocation
179    *   (in that sense, fnotifiers are really finalization handlers)
180    */
181 };
182 /* closure for C function calls, callback() is the user function
183  */
184 struct _GCClosure
185 {
186   GClosure      closure;
187   gpointer      callback;
188 };
189
190
191 /* --- prototypes --- */
192 GClosure* g_cclosure_new                        (GCallback      callback_func,
193                                                  gpointer       user_data,
194                                                  GClosureNotify destroy_data);
195 GClosure* g_cclosure_new_swap                   (GCallback      callback_func,
196                                                  gpointer       user_data,
197                                                  GClosureNotify destroy_data);
198 GClosure* g_signal_type_cclosure_new            (GType          itype,
199                                                  guint          struct_offset);
200
201
202 /* --- prototypes --- */
203 GClosure* g_closure_ref                         (GClosure       *closure);
204 void      g_closure_sink                        (GClosure       *closure);
205 void      g_closure_unref                       (GClosure       *closure);
206 /* intimidating */
207 GClosure* g_closure_new_simple                  (guint           sizeof_closure,
208                                                  gpointer        data);
209 void      g_closure_add_finalize_notifier       (GClosure       *closure,
210                                                  gpointer        notify_data,
211                                                  GClosureNotify  notify_func);
212 void      g_closure_remove_finalize_notifier    (GClosure       *closure,
213                                                  gpointer        notify_data,
214                                                  GClosureNotify  notify_func);
215 void      g_closure_add_invalidate_notifier     (GClosure       *closure,
216                                                  gpointer        notify_data,
217                                                  GClosureNotify  notify_func);
218 void      g_closure_remove_invalidate_notifier  (GClosure       *closure,
219                                                  gpointer        notify_data,
220                                                  GClosureNotify  notify_func);
221 void      g_closure_add_marshal_guards          (GClosure       *closure,
222                                                  gpointer        pre_marshal_data,
223                                                  GClosureNotify  pre_marshal_notify,
224                                                  gpointer        post_marshal_data,
225                                                  GClosureNotify  post_marshal_notify);
226 void      g_closure_set_marshal                 (GClosure       *closure,
227                                                  GClosureMarshal marshal);
228 void      g_closure_set_meta_marshal            (GClosure       *closure,
229                                                  gpointer        marshal_data,
230                                                  GClosureMarshal meta_marshal);
231 void      g_closure_invalidate                  (GClosure       *closure);
232 void      g_closure_invoke                      (GClosure       *closure,
233                                                  GValue /*out*/ *return_value,
234                                                  guint           n_param_values,
235                                                  const GValue   *param_values,
236                                                  gpointer        invocation_hint);
237
238 /* FIXME:
239    OK:  data_object::destroy            -> closure_invalidate();
240    MIS: closure_invalidate()            -> disconnect(closure);
241    MIS: disconnect(closure)             -> (unlink) closure_unref();
242    OK:  closure_finalize()              -> g_free (data_string);
243
244    random remarks:
245    - need marshaller repo with decent aliasing to base types
246    - provide marshaller collection, virtually covering anything out there
247 */
248
249 void g_cclosure_marshal_generic (GClosure     *closure,
250                                  GValue       *return_gvalue,
251                                  guint         n_param_values,
252                                  const GValue *param_values,
253                                  gpointer      invocation_hint,
254                                  gpointer      marshal_data);
255
256 G_END_DECLS
257
258 #endif /* __G_CLOSURE_H__ */