RE: Overlay Documentation

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

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

> > I agree. I think we're still figuring out whether or not the native
> > interfaces are suficient...
>
> well, I need to admit that it was a bit hard to learn how to
> use overlays,
> and I'm not sure yet what they do in some cases.  I'd like to find
> documented "obvious" things like: I note that over_op_func()
> saves a copy
> of the op->o_bd, rather than its pointer, before calling the
> overlays; is
> it because you're afraid that someone along the path may
> alter the data,
> so you just don't trust overlays, or there's a reason I'm
> missing?

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...

> 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.

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