docs/reference/gobject/tmpl/gclosure.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Closures
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9
  10 </para>
  11
  12 <!-- ##### SECTION See_Also ##### -->
  13 <para>
  14
  15 </para>
  16
  17 <!-- ##### MACRO G_CLOSURE_NEEDS_MARSHAL ##### -->
  18 <para>
  19
  20 </para>
  21
  22 @closure:
  23
  24
  25 <!-- ##### MACRO G_CLOSURE_N_NOTIFIERS ##### -->
  26 <para>
  27
  28 </para>
  29
  30 @cl:
  31
  32
  33 <!-- ##### MACRO G_CCLOSURE_SWAP_DATA ##### -->
  34 <para>
  35
  36 </para>
  37
  38 @cclosure:
  39
  40
  41 <!-- ##### MACRO G_CALLBACK ##### -->
  42 <para>
  43
  44 </para>
  45
  46 @f:
  47
  48
  49 <!-- ##### USER_FUNCTION GCallback ##### -->
  50 <para>
  51
  52 </para>
  53
  54
  55
  56 <!-- ##### STRUCT GClosure ##### -->
  57 <para>
  58
  59 </para>
  60
  61 @is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate()
  62
  63 <!-- ##### MACRO G_TYPE_CLOSURE ##### -->
  64 <para>
  65
  66 </para>
  67
  68
  69
  70 <!-- ##### STRUCT GCClosure ##### -->
  71 <para>
  72
  73 </para>
  74
  75 @closure:
  76 @callback:
  77
  78 <!-- ##### USER_FUNCTION GClosureMarshal ##### -->
  79 <para>
  80
  81 </para>
  82
  83 @closure:
  84 @return_value:
  85 @n_param_values:
  86 @param_values:
  87 @invocation_hint:
  88 @marshal_data:
  89
  90
  91 <!-- ##### USER_FUNCTION GClosureNotify ##### -->
  92 <para>
  93
  94 </para>
  95
  96 @data:
  97 @closure:
  98
  99
 100 <!-- ##### STRUCT GClosureNotifyData ##### -->
 101 <para>
 102
 103 </para>
 104
 105 @data:
 106 @notify:
 107
 108 <!-- ##### FUNCTION g_cclosure_new ##### -->
 109 <para>
 110
 111 </para>
 112
 113 @callback_func:
 114 @user_data:
 115 @destroy_data:
 116 @Returns:
 117
 118
 119 <!-- ##### FUNCTION g_cclosure_new_swap ##### -->
 120 <para>
 121
 122 </para>
 123
 124 @callback_func:
 125 @user_data:
 126 @destroy_data:
 127 @Returns:
 128
 129
 130 <!-- ##### FUNCTION g_cclosure_new_object ##### -->
 131 <para>
 132
 133 </para>
 134
 135 @callback_func:
 136 @object:
 137 @Returns:
 138
 139
 140 <!-- ##### FUNCTION g_cclosure_new_object_swap ##### -->
 141 <para>
 142
 143 </para>
 144
 145 @callback_func:
 146 @object:
 147 @Returns:
 148
 149
 150 <!-- ##### FUNCTION g_closure_new_object ##### -->
 151 <para>
 152
 153 </para>
 154
 155 @sizeof_closure:
 156 @object:
 157 @Returns:
 158
 159
 160 <!-- ##### FUNCTION g_closure_ref ##### -->
 161 <para>
 162 Increment the reference count on a closure to force it staying
 163 alive while the caller holds a pointer to it.
 164 </para>
 165
 166 @closure: #GClosure to increment the reference count on
 167 @Returns: The @closure passed in, for convenience
 168
 169
 170 <!-- ##### FUNCTION g_closure_sink ##### -->
 171 <para>
 172 Take over the initial ownership of a closure.
 173 When closures are newly created, they get an initial reference count
 174 of 1, eventhough no caller has yet invoked g_closure_ref() on the @closure.
 175 Code entities that store closures for notification purposes are supposed
 176 to call this function, for example like this:
 177 <msgtext><programlisting>
 178 static GClosure *notify_closure = NULL;
 179 void
 180 foo_notify_set_closure (GClosure *closure)
 181 {
 182   if (notify_closure)
 183     g_closure_unref (notify_closure);
 184   notify_closure = closure;
 185   if (notify_closure)
 186     {
 187       g_closure_ref (notify_closure);
 188       g_closure_sink (notify_closure);
 189     }
 190 }
 191 </programlisting></msgtext>
 192 Because g_closure_sink() may decrement the reference count of a closure
 193 (if it hasn't been called on @closure yet) just like g_closure_unref(),
 194 g_closure_ref() should be called prior to this function.
 195 </para>
 196
 197 @closure: #GClosure to decrement the initial reference count on, if it's
 198           still being held
 199
 200
 201 <!-- ##### FUNCTION g_closure_unref ##### -->
 202 <para>
 203 Decrement the reference count of a closure after it was
 204 previously incremented by the same caller. The closure
 205 will most likely be destroyed and freed after this function
 206 returns.
 207 </para>
 208
 209 @closure: #GClosure to decrement the reference count on
 210
 211
 212 <!-- ##### FUNCTION g_closure_invoke ##### -->
 213 <para>
 214
 215 </para>
 216
 217 @closure:
 218 @return_value:
 219 @n_param_values:
 220 @param_values:
 221 @invocation_hint:
 222
 223
 224 <!-- ##### FUNCTION g_closure_invalidate ##### -->
 225 <para>
 226 This function sets a flag on the closure to indicate that it's
 227 calling environment has become invalid, and thus causes any future
 228 invocations of g_closure_invoke() on this @closure to be ignored.
 229 Also, invalidation notifiers installed on the closure will be called
 230 at this point, and since invalidation notifiers may unreference
 231 the closure, @closure should be considered an invalidated pointer
 232 atfer this function, unles g_closure_ref() was called beforehand.
 233 </para>
 234
 235 @closure: GClosure to invalidate
 236
 237
 238 <!-- ##### FUNCTION g_closure_add_finalize_notifier ##### -->
 239 <para>
 240
 241 </para>
 242
 243 @closure:
 244 @notify_data:
 245 @notify_func:
 246
 247
 248 <!-- ##### FUNCTION g_closure_add_invalidate_notifier ##### -->
 249 <para>
 250
 251 </para>
 252
 253 @closure:
 254 @notify_data:
 255 @notify_func:
 256
 257
 258 <!-- ##### FUNCTION g_closure_remove_finalize_notifier ##### -->
 259 <para>
 260
 261 </para>
 262
 263 @closure:
 264 @notify_data:
 265 @notify_func:
 266
 267
 268 <!-- ##### FUNCTION g_closure_remove_invalidate_notifier ##### -->
 269 <para>
 270
 271 </para>
 272
 273 @closure:
 274 @notify_data:
 275 @notify_func:
 276
 277
 278 <!-- ##### FUNCTION g_closure_new_simple ##### -->
 279 <para>
 280
 281 </para>
 282
 283 @sizeof_closure:
 284 @data:
 285 @Returns:
 286
 287
 288 <!-- ##### FUNCTION g_closure_set_marshal ##### -->
 289 <para>
 290
 291 </para>
 292
 293 @closure:
 294 @marshal:
 295
 296
 297 <!-- ##### FUNCTION g_closure_add_marshal_guards ##### -->
 298 <para>
 299
 300 </para>
 301
 302 @closure:
 303 @pre_marshal_data:
 304 @pre_marshal_notify:
 305 @post_marshal_data:
 306 @post_marshal_notify:
 307
 308
 309 <!-- ##### FUNCTION g_closure_set_meta_marshal ##### -->
 310 <para>
 311
 312 </para>
 313
 314 @closure:
 315 @marshal_data:
 316 @meta_marshal:
 317
 318
 319 <!-- ##### FUNCTION g_source_set_closure ##### -->
 320 <para>
 321
 322 </para>
 323
 324 @source:
 325 @closure:
 326
 327
 328 <!-- ##### MACRO G_TYPE_IO_CHANNEL ##### -->
 329 <para>
 330
 331 </para>
 332
 333
 334
 335 <!-- ##### MACRO G_TYPE_IO_CONDITION ##### -->
 336 <para>
 337
 338 </para>
 339
 340
 341