fixed dealing with collection/lcopy of NULL values.
[platform/upstream/glib.git] / gobject / gclosure.h
1 /* GObject - GLib Type, Object, Parameter and Signal Library
2  * Copyright (C) 2000 Red Hat, Inc.
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General
15  * Public License along with this library; if not, write to the
16  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
17  * Boston, MA 02111-1307, USA.
18  */
19 #ifndef __G_CLOSURE_H__
20 #define __G_CLOSURE_H__
21
22
23 #include        <gobject/gtype.h>
24
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif /* __cplusplus */
29
30
31
32 /* --- defines --- */
33 #define G_CLOSURE_NEEDS_MARSHAL(closure) (((GClosure*) (closure))->marshal == NULL)
34 #define G_CCLOSURE_SWAP_DATA(cclosure)   (((GClosure*) (closure))->derivative_flag)
35 #define G_CALLBACK(f)                    ((GCallback) (f))
36
37
38 /* -- typedefs --- */
39 typedef struct _GClosure                 GClosure;
40 typedef struct _GClosureNotifyData       GClosureNotifyData;
41 typedef gpointer GCallback;
42 typedef void  (*GClosureNotify)         (gpointer        data,
43                                          GClosure       *closure);
44 typedef void  (*GClosureMarshal)        (GClosure       *closure,
45                                          GValue         *return_value,
46                                          guint           n_param_values,
47                                          const GValue   *param_values,
48                                          gpointer        invocation_hint,
49                                          gpointer        marshal_data);
50 typedef struct _GCClosure                GCClosure;
51
52
53 /* --- structures --- */
54 struct _GClosureNotifyData
55 {
56   gpointer       data;
57   GClosureNotify notify;
58 };
59 struct _GClosure
60 {
61   /*< private >*/       guint    ref_count : 15;
62   /*< private >*/       guint    meta_marshal : 1;
63   /*< private >*/       guint    n_guards : 1;
64   /*< private >*/       guint    n_fnotifiers : 2;      /* finalization notifiers */
65   /*< private >*/       guint    n_inotifiers : 8;      /* invalidation notifiers */
66   /*< private >*/       guint    in_inotify : 1;
67   /*< private >*/       guint    floating : 1;
68   /*< protected >*/     guint    derivative_flag : 1;
69   /*< puplic >*/        guint    in_marshal : 1;
70   /*< public >*/        guint    is_invalid : 1;
71
72   /*< private >*/       void   (*marshal)  (GClosure       *closure,
73                                             GValue /*out*/ *return_value,
74                                             guint           n_param_values,
75                                             const GValue   *param_values,
76                                             gpointer        invocation_hint,
77                                             gpointer        marshal_data);
78   /*< protected >*/     gpointer data;
79
80   /*< private >*/       GClosureNotifyData *notifiers;
81
82   /* invariants/constrains:
83    * - ->marshal and ->data are _invalid_ as soon as ->is_invalid==TRUE
84    * - invocation of all inotifiers occours prior to fnotifiers
85    * - order of inotifiers is random
86    *   inotifiers may _not_ free/invalidate parameter values (e.g. ->data)
87    * - order of fnotifiers is random
88    * - notifiers may only be removed before or during their invocation
89    * - reference counting may only happen prior to fnotify invocation
90    *   (in that sense, fnotifiers are really finalization handlers)
91    */
92 };
93 /* closure for C function calls, callback() is the user function
94  */
95 struct _GCClosure
96 {
97   GClosure      closure;
98   gpointer      callback;
99 };
100
101
102 /* --- prototypes --- */
103 GClosure*       g_cclosure_new                  (GCallback      callback_func,
104                                                  gpointer       user_data,
105                                                  GClosureNotify destroy_data);
106 GClosure*       g_cclosure_new_swap             (GCallback      callback_func,
107                                                  gpointer       user_data,
108                                                  GClosureNotify destroy_data);
109 GClosure*       g_signal_type_cclosure_new      (GType          itype,
110                                                  guint          struct_offset);
111
112
113 /* --- prototypes --- */
114 GClosure*       g_closure_ref                   (GClosure       *closure);
115 void            g_closure_unref                 (GClosure       *closure);
116 /* intimidating */
117 GClosure*       g_closure_new_simple            (guint           sizeof_closure,
118                                                  gpointer        data);
119 void            g_closure_add_fnotify           (GClosure       *closure,
120                                                  gpointer        notify_data,
121                                                  GClosureNotify  notify_func);
122 void            g_closure_remove_fnotify        (GClosure       *closure,
123                                                  gpointer        notify_data,
124                                                  GClosureNotify  notify_func);
125 void            g_closure_add_inotify           (GClosure       *closure,
126                                                  gpointer        notify_data,
127                                                  GClosureNotify  notify_func);
128 void            g_closure_remove_inotify        (GClosure       *closure,
129                                                  gpointer        notify_data,
130                                                  GClosureNotify  notify_func);
131 void            g_closure_add_marshal_guards    (GClosure       *closure,
132                                                  gpointer        pre_marshal_data,
133                                                  GClosureNotify  pre_marshal_notify,
134                                                  gpointer        post_marshal_data,
135                                                  GClosureNotify  post_marshal_notify);
136 void            g_closure_set_marshal           (GClosure       *closure,
137                                                  GClosureMarshal marshal);
138 void            g_closure_set_meta_marshal      (GClosure       *closure,
139                                                  gpointer        marshal_data,
140                                                  GClosureMarshal meta_marshal);
141 void            g_closure_invalidate            (GClosure       *closure);
142 void            g_closure_invoke                (GClosure       *closure,
143                                                  GValue /*out*/ *return_value,
144                                                  guint           n_param_values,
145                                                  const GValue   *param_values,
146                                                  gpointer        invocation_hint);
147
148
149 /* FIXME:
150    OK:  data_object::destroy            -> closure_invalidate();
151    MIS: closure_invalidate()            -> disconnect(closure);
152    MIS: disconnect(closure)             -> (unlink) closure_unref();
153    OK:  closure_finalize()              -> g_free (data_string);
154
155    random remarks:
156    - need marshaller repo with decent aliasing to base types
157    - provide marshaller collection, virtually covering anything out there
158 */
159
160
161 #ifdef __cplusplus
162 }
163 #endif /* __cplusplus */
164
165 #endif /* __G_CLOSURE_H__ */