glib/gobject/gclosure.h

/* GObject - GLib Type, Object, Parameter and Signal Library
 * Copyright (C) 2000 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General
 * Public License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
 * Boston, MA 02111-1307, USA.
 */
#ifndef __G_CLOSURE_H__
#define __G_CLOSURE_H__


#include        <gobject/gtype.h>


#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */



/* --- defines --- */
#define	G_CLOSURE_NEEDS_MARSHAL(closure) (((GClosure*) (closure))->marshal == NULL)
#define	G_CCLOSURE_SWAP_DATA(cclosure)	 (((GClosure*) (closure))->derivative_flag)


/* -- typedefs --- */
typedef struct _GClosure		 GClosure;
typedef struct _GClosureNotifyData	 GClosureNotifyData;
typedef	gpointer GCallback;
typedef void  (*GClosureNotify)		(gpointer	 data,
					 GClosure	*closure);
typedef void  (*GClosureMarshal)	(GClosure	*closure,
					 GValue         *return_value,
					 guint           n_param_values,
					 const GValue   *param_values,
					 gpointer        invocation_hint,
					 gpointer	 marshal_data);
typedef struct _GCClosure		 GCClosure;


/* --- structures --- */
struct _GClosureNotifyData
{
  gpointer       data;
  GClosureNotify notify;
};
struct _GClosure
{
  /*< private >*/	guint	 ref_count : 15;
  /*< private >*/	guint	 meta_marshal : 1;
  /*< private >*/	guint	 n_guards : 1;
  /*< private >*/	guint	 n_fnotifiers : 2;	/* finalization notifiers */
  /*< private >*/	guint	 n_inotifiers : 8;	/* invalidation notifiers */
  /*< private >*/	guint	 in_inotify : 1;
  /*< private >*/	guint	 floating : 1;
  /*< protected >*/	guint	 derivative_flag : 1;
  /*< puplic >*/	guint	 in_marshal : 1;
  /*< public >*/	guint	 is_invalid : 1;

  /*< private >*/	void   (*marshal)  (GClosure       *closure,
					    GValue /*out*/ *return_value,
					    guint           n_param_values,
					    const GValue   *param_values,
					    gpointer        invocation_hint,
					    gpointer	    marshal_data);
  /*< protected >*/	gpointer data;

  /*< private >*/	GClosureNotifyData *notifiers;

  /* invariants/constrains:
   * - ->marshal and ->data are _invalid_ as soon as ->is_invalid==TRUE
   * - invocation of all inotifiers occours prior to fnotifiers
   * - order of inotifiers is random
   *   inotifiers may _not_ free/invalidate parameter values (e.g. ->data)
   * - order of fnotifiers is random
   * - notifiers may only be removed before or during their invocation
   * - reference counting may only happen prior to fnotify invocation
   *   (in that sense, fnotifiers are really finalization handlers)
   */
};
/* closure for C function calls, callback() is the user function
 */
struct _GCClosure
{
  GClosure	closure;
  gpointer	callback;
};


/* --- prototypes --- */
GClosure*	g_cclosure_new			(GCallback	callback_func,
						 gpointer	user_data,
						 GClosureNotify destroy_data);
GClosure*	g_cclosure_new_swap		(GCallback	callback_func,
						 gpointer	user_data,
						 GClosureNotify destroy_data);
GClosure*	g_signal_type_closure_new	(GType          itype,
						 guint          struct_offset);


/* --- prototypes --- */
GClosure*	g_closure_ref			(GClosure	*closure);
void		g_closure_unref			(GClosure	*closure);
/* intimidating */
GClosure*	g_closure_new_simple		(guint		 sizeof_closure,
						 gpointer	 data);
void		g_closure_add_fnotify		(GClosure       *closure,
						 gpointer	 notify_data,
						 GClosureNotify	 notify_func);
void		g_closure_remove_fnotify	(GClosure       *closure,
						 gpointer	 notify_data,
						 GClosureNotify	 notify_func);
void		g_closure_add_inotify		(GClosure       *closure,
						 gpointer	 notify_data,
						 GClosureNotify	 notify_func);
void		g_closure_remove_inotify	(GClosure       *closure,
						 gpointer	 notify_data,
						 GClosureNotify	 notify_func);
void		g_closure_add_marshal_guards	(GClosure	*closure,
						 gpointer        pre_marshal_data,
						 GClosureNotify	 pre_marshal_notify,
						 gpointer        post_marshal_data,
						 GClosureNotify	 post_marshal_notify);
void		g_closure_set_marshal		(GClosure	*closure,
						 GClosureMarshal marshal);
void		g_closure_set_meta_marshal	(GClosure       *closure,
						 gpointer	 marshal_data,
						 GClosureMarshal meta_marshal);
void		g_closure_invalidate		(GClosure	*closure);
void		g_closure_invoke		(GClosure 	*closure,
						 GValue	/*out*/	*return_value,
						 guint		 n_param_values,
						 const GValue	*param_values,
						 gpointer	 invocation_hint);


/* FIXME:
  data_object::destroy		-> closure_invalidate();
  closure_invalidate()		-> disconnect(closure);
  disconnect(closure)		-> (unlink) closure_unref();
  closure_finalize()		-> g_free (data_string);
  
  1) need GObject and GType in glib
  2) need GParam
  3) need to resolve dtor cycles
  4) need GSignal move
  5) destroy on last caller ref or last data ref?
  
  
  random remarks:
  - don't mandate signals for GObject
  - OTOH, don't mandate GObject for GSignal
  - need marshaller repo with decent aliasing to base types
  - provide marshaller collection, virtually covering anything out there
  - at that point, still need GSignalCMarhsaller to g_signal_new() ?
  - can we combine varargs collect mechanisms with marshaller stubs?
  for out values (i.e. returntypes), that might get rid of the following
  point...
  - char* return signals with connections ala:
  connect({ return "static data that can't work"; }),
  connect({ return g_strdup ("properly duplicated string"); })
  won't work anymore. CRASH

  problems:
  - accumulator needs gboolean to indicate EMISSION_STOP
  - accumulator needs data
*/


#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* __G_CLOSURE_H__ */