The new modules system

[Jelmer Vernooij]

Hi,

I've finally committed my modules patch to CVS. Here are the docs (now 
in dev-doc as well). 

Next things I'll work on:

- Adapting VFS to use the new modules system
- Winsdb (after metze resends his patch)

Tomorrow I continue learning for my exams so the VFS patch 
probably won't come until next week,

Jelmer

Chapter 14. Modules

14.1. Advantages

   The new modules system has the following advantages:

   Transparent loading of static and shared modules (no need for
   a subsystem to know about modules)
   Simple selection between shared and static modules at
   configure time
   "preload modules" option for increasing performance for stable
   modules
   No nasty #define stuff anymore
   All backends are available as plugin now (including pdb_ldap
   and pdb_tdb)
     _________________________________________________________

14.2. Loading modules

   Some subsystems in samba use different backends. These
   backends can be either statically linked in to samba or
   available as a plugin. A subsystem should have a function that
   allows a module to register itself. For example, the passdb
   subsystem has:

BOOL smb_register_passdb(const char *name, pdb_init_function init, int
version);

   This function will be called by the initialisation function of
   the module to register itself.
     _________________________________________________________

14.2.1. Static modules

   The modules system compiles a list of initialisation functions
   for the static modules of each subsystem. This is a define.
   For example, it is here currently (from include/config.h):

/* Static init functions */
#define static_init_pdb { pdb_mysql_init(); pdb_ldap_init(); pdb_smbpas
swd_init(); pdb_tdbsam_init(); pdb_guest_init();}

   These functions should be called before the subsystem is used.
   That can be done either from the executable that will be using
   the subsystem ( static_init_rpc is called from the main()
   function of smbd), or from the subsystem itself when it's
   first used (like passdb's lazy_initialise_passdb does).
     _________________________________________________________

14.2.2. Shared modules

   If a subsystem needs a certain backend, it should check if it
   has already been registered. If the backend hasn't been
   registered already, the subsystem should call
   smb_probe_module(char *subsystem, char *backend). This
   function tries to load the correct module from a certain path
   ($LIBDIR/subsystem/backend.so). If the first character in
   'backend' is a slash, smb_probe_module() tries to load the
   module from the absolute path specified in 'backend'.

   After smb_probe_module() has been executed, the subsystem
   should check again if the module has been registered.
     _________________________________________________________

14.3. Writing modules

   Each module has an initialisation function. For modules that
   are included with samba this name is 'subsystem_backend_init'.
   For external modules (that will never be built-in, but only
   available as a module) this name is always 'init_module'. (In
   the case of modules included with samba, the configure system
   will add a #define subsystem_backend_init() init_module()).
   The prototype for these functions is:

int init_module(void);

   This function should call one or more registration functions.
   The function should return non-zero on success and zero on
   failure.

   For example, pdb_ldap_init() contains:

int pdb_ldap_init(void)
{
    smb_register_passdb("ldapsam", pdb_init_ldapsam, PASSDB_INTERFACE_V
ERSION);
    smb_register_passdb("ldapsam_nua", pdb_init_ldapsam_nua, PASSDB_INT
ERFACE_VERSION);
        return TRUE;
}
     _________________________________________________________

14.3.1. Static/Shared selection in configure.in

   Some macros in configure.in generate the various defines and
   substs that are necessary for the system to work correct. All
   modules that should be built by default have to be added to
   the variable 'default_modules'. For example, if ldap is found,
   pdb_ldap is added to this variable.

   On the bottom of configure.in, SMB_MODULE() should be called
   for each module and SMB_SUBSYSTEM() for each subsystem.

   Syntax:

SMB_MODULE($MODULE_subsystem_backend, subsystem_backend, object files,
plugin name, subsystem name)
SMB_SUBSYSTEM(subsystem)

-- 
Jelmer Vernooij                                      <jelmer at samba.org>
Pending (unfinished) patches                         http://samba.org/~jelmer/diffs.php
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.samba.org/archive/samba-technical/attachments/20030320/f20e9f64/attachment.bin