RE: Overlay Documentation

["Pierangelo Masarati" <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!!!

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;


>
>> In my
>> overlays I usually save a pointer to data I beed to replace
>> and restore.
>> Again: I noted that in some cases, in back-relay, I need to explicitly
>> restore the callbacks removing the one I added; why? ... In
>> this sense a
>> schematical documentation would help in finding out what the
>> code does.
>
> Well, I'm hoping to smooth this out better as time goes on. You have to
> be careful about inserting or replacing callbacks because other things
> may still be relying on them. E.g., your overlay may be on a database
> that is part of a backglue subordinate tree, which also uses callbacks.
>
>> I
>> know the code is the source, but when it gets too involved
>> (and callbacks
>> and nested structure casting are a bit too involved for me)
>> it gets really
>> hard to tell what it does. I admit I'm learning a lot from
>> your examples,
>> and I really appreciate it, but sometimes I find it easier to
>> learn form
>> docs rather than from examples :)
>
> 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...

Ando.

-- 
Pierangelo Masarati
mailto:pierangelo.masarati@sys-net.it