lbd modules and recursion

[Simo Sorce]

Hi all,
discussing on IRC with Andrew Bartlet we come to talk about ldb modules
and recursion and how to handle ldb operations inside modules.

By design ldb modules must be reentrant and support recursion.

In case you need to write a module special care MUST be taken in this
respect. You have to handle things in a way that let you avoid getting
into loops.
Any ldb operation can be called by upper or lower ldb modules and the
programmer must be prepared to handle that situation.
Furthermore you should _never_ call ldb_next_request() to start a new
operation.

You must issue the ldb_xxx() ( or ldb_request() ) operation exposed in
the ldb API as any new operation must go through all the stack.

Suppose you need o issue an ldb_modify() operation during an ldb_add()
operation and have the following stack:

API entry point
 - paged_results
 - sort
 - rdn_name
 - operational
 - schema
 - <your brand new module>
__ ldb_tdb

you must not set up a new ldb_request structure and call
ldb_next_request() otherwise that will jump directly to the ldb_tdb
backend.

Doing this would mean you skip rdn_name and operational modules which
must be called and run on an ldb_modify() operation, and would also skip
the schema module that will assure your mods are legal.

That must not happen ever. (In theory the schema module MUST always be
the latest one, but this is just an example for educational purposes).

Another thing the programmer of ldb modules should not make assumptions
about its position in the stack. You should not assume you are always
the first or the last module or that the previous or following module
will do something special or be some specified module.

That does not mean that certain module will be placed in a certain way,
the schema module should be the last module for any
ldb_add()/ldb_modify()/ldb_delete() operation but under it can easily
stay yanother module that handles searches, etc in a special way. For
example there may or not be a special "partitions" module (not existing
yet) that can split call across multiple ldbs or something like that.

In the case of the "partitions" module it becomes even more evident that
calling ldb_next_request() is wrong, as by doing so you may not reach a
good part of the global tree.

eg:
                                    - your_module(1) - ldb_tdb1
 module1 -> module2 -> partitions _/ _ ldb_tdb2
                                   \_ your_module(2) - ldb_ldap

Another example is that paged_result should always be the first module
in the stack, or anyway the first that modifies searches, but again that
does not mean you can assume under a programming point of view that it
will really always be the first module.

Order will be suggested by the functions performed by the module but, I
want to stress that you shouldn't make this a general assumption in the
code.

Hope this mail clarifies things a bit, if not please feel free to
comment.

Simo.

-- 
Simo Sorce    -  idra at samba.org
Samba Team    -  http://www.samba.org
Italian Site  -  http://samba.xsec.it