Bug 556489 – callback annotations

2008-01-03  Andreas Rottmann  <a.rottmann@gmx.at>

	Bug 556489 – callback annotations
	
	* giscanner/transformer.py 

	* tools/generate.c (write_callable_info): Write out the new scope,
	closure and destroy attributes.

	* giscanner/transformer.py (Transformer._type_is_callback): New
	method, checking if a given type is a callback.
	(Transformer._augment_callback_params): New method; adds
	information (closure, destroy) to callback parameters.
	(Transformer._handle_closure, Transformer._handle_destroy): New methods, 
	auxiliary to _augment_callback_params.
	(Transformer._create_function): Call _augment_callback_params().
	(Transformer._create_parameter): Handle scope option.

	(Transformer._create_typedef_callback): New method, creates a
	callback, and registers it in the typedef namespace
	(Transformer._create_typedef): Use _create_typedef_callback()
	instead of the plain _create_callback().

	* giscanner/ast.py (Parameter): Added callback-related fields.
	* giscanner/girwriter.py: Write out new Parameter fields.

	* girepository/girnode.h (GIrNodeParam): Added fields scope, 
	closure and destroy.
	* girepository/gtypelib.h (ArgBlob): Ditto.
	* girepository/girparser.c (start_parameter): Handle new fields.

	* girepository/girmodule.c (g_ir_module_build_typelib): Adjust
	arg_blob_size, bump major version due to this change.
	* girepository/girnode.c (g_ir_node_get_full_size_internal)
	(g_ir_node_build_typelib)
	* girepository/gtypelib.c (g_typelib_check_sanity): ArgBlob size
	adjustments.
	(g_ir_node_build_typelib): Fill in new ArgBlob flags from param. 

	* girepository/girepository.h (GIScope): New enumeration, listing
	the different possible scopes for callbacks.

	* girepository/ginfo.c (g_arg_info_get_scope)
	(g_arg_info_get_closure, g_arg_info_get_destroy): Accessors for
	callback-related argument indices (callback scope, closure for a
	callback, destroy notification for a callback).

	* tests/scanner/: Added testcases for new features.

svn path=/trunk/; revision=998

1 files changed, 30 insertions, 2 deletions

diff --git a/docs/typelib-format.txt b/docs/typelib-format.txt
index 895c1f0d..a47a9f78 100644
--- a/docs/typelib-format.txt
+++ b/docs/typelib-format.txt
@@ -391,7 +391,11 @@ struct ArgBlob
   guint          transfer_ownership           : 1;
   guint          transfer_container_ownership : 1;
   guint          is_return_value              : 1;
-  guint          reserved                     :24:
+  guint          scope                        : 3;
+  guint          reserved                     :21:
+
+  gint8        closure;
+  gint8        destroy;
 
   SimpleTypeBlob arg_type;
 }
@@ -437,7 +441,31 @@ is_return_value:
           at most one per function call. If an out parameter is marked as 
           return value, the actual return value of the function should be 
           either void or a boolean indicating the success of the call.
-  
+
+scope: 
+	  If the parameter is of a callback type, this denotes the scope
+	  of the user_data and the callback function pointer itself
+	  (for languages that emit code at run-time).
+
+	    0 invalid -- the argument is not of callback type
+	    1 call -- the callback and associated user_data is 
+	      only used during the call to this function
+	    2 object -- the callback and associated user_data is 
+	      used until the object containing this method is destroyed
+	    3 async -- the callback and associated user_data is 
+	      only used until the callback is invoked, and the callback 
+	      is invoked always exactly once.
+	    4 notified -- the callback and and associated user_data is
+	      used until the caller is notfied via the destroy_notify
+
+closure:
+	  Index of the closure (user_data) parameter associated with the callback, 
+	  or -1.
+
+destroy:
+	  Index of the destroy notfication callback parameter associated with 
+	  the callback, or -1.
+
 arg_type:
           Describes the type of the parameter. See details below.