Re: [gdome]EventListener "priv" field

[Luca Padovani <lpadovan cs unibo it>]

Hi Paolo,

On Wed, 2003-02-19 at 09:29, Paolo Casarini wrote:
> I agree with you and I consider this a good extesion for the library
> features list. It could be also useful an example that explain a good 
> way to use it.

I've just committed the needed modifications. I had to run apigen by
hand and copy the generated files in the right place. Not sure this is
the right thing to do.

Some more detailed explanations on when we need the mechanism: say we
have to associate some data with a particular EventListener. We may
choose to store it in user_data, but this is dangerous as you have no
control on what users can do with user_data, so it is better to store it
in the private "priv" field of EventListener. The reason why
EventListener is the only candidate with such strange requirements is
that it basically implements a callback mechanism which you might have
to propagate to another binding (to an Ocaml function, for instance).
Now, if the data you store in "priv" is subject to some memory
management system (either reference counting or garbage collection), you
have to take that into account. Registering or reffing the data is easy,
because that is done in conjunction with the creation of the
EventListener object. Unregistering or unreffing the data is not trivial
in general, because that will happen as soon as the EventListener is
finalized and determining the time at which an object is finalized is
impossible. Hence the idea is to have a callback function that you
associate with the EventListener and that is called just before
finalization, when the ref counter of the EventListener reaches zero.
The callback function may take care of unregistering or unreffing the
private data.

The following example is a slightly simplified version of our Ocaml
binding of gdome2 (the mail continues after the example!)

--------------------------------------------------------------------------
/* the following is the C function that calls the Ocaml function that
 * has to react to the Event when it is fired
 */
void ml_gdome_evntl_callback(GdomeEventListener* self, 
                             GdomeEvent* event, GdomeException* exc)
{
  value cb = gdome_evntl_get_priv(self);
  /* invoke Ocaml function from C */
  callback(cb, Val_Event(event));
}

/* the following is the C function that is called just before 
 * finalization of the EventListener object
 */
void ml_gdome_evntl_priv_callback(GdomeEventListener* self)
{
  /* the self EventListener object is about to be destroyed,
   * so we inform the Ocaml garbage collector the value stored
   * in it is not used anymore
   */
  remove_global_root(gdome_evntl_get_priv(self));
}

/* the following is the constructor of the Ocaml object corresponding to
 * an EventListener object
 */
value ml_gdome_evntl_create(value callback)
{
  ...
  /* register the callback value so that the Ocaml garbage collector
   * knows it is referenced from somewhere
   */
  register_global_root(callback);
  ... = gdome_evntl_aux_mkref(ml_gdome_evntl_callback, callback, 
                              ml_gdome_evntl_priv_callback);
  return ...
}
--------------------------------------------------------------------------

When do you think a new release will be ready? Is there anything else
urgent that is currently pending?

-- luca