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
29G_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 --- */
76typedef struct _GClosure		 GClosure;
77typedef 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 */
88typedef 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 */
97typedef 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 */
114typedef 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 */
127typedef struct _GCClosure		 GCClosure;
128
129
130/* --- structures --- */
131struct _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 */
145struct _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 */
184struct _GCClosure
185{
186  GClosure	closure;
187  gpointer	callback;
188};
189
190
191/* --- prototypes --- */
192GClosure* g_cclosure_new			(GCallback	callback_func,
193						 gpointer	user_data,
194						 GClosureNotify destroy_data);
195GClosure* g_cclosure_new_swap			(GCallback	callback_func,
196						 gpointer	user_data,
197						 GClosureNotify destroy_data);
198GClosure* g_signal_type_cclosure_new		(GType          itype,
199						 guint          struct_offset);
200
201
202/* --- prototypes --- */
203GClosure* g_closure_ref				(GClosure	*closure);
204void	  g_closure_sink			(GClosure	*closure);
205void	  g_closure_unref			(GClosure	*closure);
206/* intimidating */
207GClosure* g_closure_new_simple			(guint		 sizeof_closure,
208						 gpointer	 data);
209void	  g_closure_add_finalize_notifier	(GClosure       *closure,
210						 gpointer	 notify_data,
211						 GClosureNotify	 notify_func);
212void	  g_closure_remove_finalize_notifier	(GClosure       *closure,
213						 gpointer	 notify_data,
214						 GClosureNotify	 notify_func);
215void	  g_closure_add_invalidate_notifier	(GClosure       *closure,
216						 gpointer	 notify_data,
217						 GClosureNotify	 notify_func);
218void	  g_closure_remove_invalidate_notifier	(GClosure       *closure,
219						 gpointer	 notify_data,
220						 GClosureNotify	 notify_func);
221void	  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);
226void	  g_closure_set_marshal			(GClosure	*closure,
227						 GClosureMarshal marshal);
228void	  g_closure_set_meta_marshal		(GClosure       *closure,
229						 gpointer	 marshal_data,
230						 GClosureMarshal meta_marshal);
231void	  g_closure_invalidate			(GClosure	*closure);
232void	  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
249G_END_DECLS
250
251#endif /* __G_CLOSURE_H__ */
252