RE: Overlay Documentation

["Howard Chu" <hyc@highlandsun.com>]

> -----Original Message-----
> From: Pierangelo Masarati [mailto:ando@sys-net.it]

> > The original content of op->o_bd is the single structure set up at
> > config time. This is a shared data structure. When processing the
> > overlay invocations, op->o_bd is modified to carry the
> state for each
> > overlay instance. The shared structure must be preserved
> intact to allow
> > concurrency...
>
> I really expect that no-one changes the __contents__ of op->o_bd
> (i.e. *op->o_bd) but I think I should be allowed to change
> op->o_bd to make it point to another data structure (e.g., in
> back-relay, I need to put the real database structure when
> dealing with operations, and add a callback that restores the
> virtual database structure during response, and the real database
> on cleanup; then the operation function of the backend will
> restore the virtual structure again!!!

What I meant is that the structure is shared on entry to over_op_func. That
function makes a local copy, which can then be overwritten at will.
op->o_bd._bd_info is set to a given overlay's overinst before calling the
overlay, and this is the important part that must support concurrency.

Probably the current over_op_func is not robust enough; it should explicitly
set op->o_bd = &db before invoking each overlay, so that if an overlay
doesn't clean up after itself no harm is done.

The flow of control here is much the same as for chain.c and pcache.c, they
also plug a real backend underneath the virtual...

> this is the stack invocation sequence:
>
> => frontend->request: op->o_bd==virtual;
>     => virtual_database: rewrite; op->o_bd=real;
>         => real_database: op->o_bd==real; do the work;
>             => response: op­->o_bd==real;
>                 => virtual_callback: op->o_bd=virtual;
>                 => rwm_overlay_callback: op->o_bd==virtual; rewrite;
>             => send response op->o_bd==virtual;
>                 => virtual_cleanup: op->o_bd=real;
>         => real_database: op->o_bd==real; continue;
>     => virtual_database: op->o_bd=virtual;
> => frontend: op->o_bd==virtual; continue;

> > I'm still learning from my examples too... (Notice the
> recent changes
> > needed to fix the proxy cache overlay...) I'll try to produce some
> > programming notes as a starting point for more complete docs later.
>
> I'm sure this will help; it will also help to find out how to
> improve the
> design in a consistent and safe manner.  I think this piece of code is
> simply great, since it is already allowing to add new complex
> features in
> a really short time...

It has definitely been handy...

  -- Howard Chu
  Chief Architect, Symas Corp.       Director, Highland Sun
  http://www.symas.com               http://highlandsun.com/hyc
  Symas: Premier OpenSource Development and Support