Multithreaded applications in ldapext-ldap-c-api-01

["Kurt D. Zeilenga" <Kurt@OpenLDAP.Org>]

I would to extend the API to support some basic
compile time and run time checking of thread
safeness.  I also have some comments in regarding
Section 23.1, p 60.


LDAP_API_FEATURE_THREAD_SAFE

If defined, the implementation can be used in
a threaded environment where all LDAP API 
calls are restricted to one thread of execution.
This feature SHOULD be implemented.

LDAP_API_FEATURE_SESSION_THREAD_SAFE

If defined, the implementation can be used
in a threaded environment where all LDAP API
calls associated with a LDAP session are
restricted to one thread of execution.  LDAP
global operations and ldap_init()/ldap_open()
calls, however, are restricted to one thread.
This feature is RECOMMENDED to be implemented.

LDAP_API_FEATURE_OPERATION_THREAD_SAFE

If defined, the implementation can be used in a
threaded environment without restriction.  The
threading model may be dictated by the implementation.
Optionally, the implementation may provide a mechanism
for allowing appplications to providing required threading
routines.  If such a mechanism is provided, additional
API features should be defined.

---
Implementing LDAP_API_FEATURE_THREAD_SAFE is rather straight
forward.   Basically, implementations just have to avoid
using any non-threadsafe/non-reentrant library calls.

Implementing LDAP_API_FEATURE_SESSION_SAFE may require a
some more involved effort to implement, but should not
requiring use of any thread library support.  The only
issue I see is with global operations and ldap_init/open().
Such that thread library support is not needed by the
implementation, I've proposed that global calls and
ldap_init/open() they be restricted to one thread.

Implementing LDAP_API_FEATURE_OPERATION_THREAD_SAFE would
require the implementation to use a thread library support
and be much more involved.  As such, the specification
should give the implementers a wide range of options.  I
feel that implementer should be allowed to dictate the
thread library used if he/she chooses to.  If he/she does,
he/she should probably provide a non threaded implementation
as well.  But that should be the implementor's choice.

However, I do also support efforts to define a common
mechanism to allow the application developer to provide
the necessary threading routines.  I believe implementers
of LDAP_API_FEATURE_OPERATION_THREAD_SAFE should NOT
be required to implement it.

When does the implementation initialize any thread
specific information?  On the first call?  Or based
upon initialization request using either a specific
API call, ie: ldap_initialize() (yuk).  Or maybe
as a side affect of an specific ldap_set_option()
operation, ie: ldap_set_option(NULL, LDAP_OPT_THREADING,
LDAP_OPT_ON) (yuk^2).

I suggest that the threading specification require
the successful completion of any LDAP API routine before
any multithreading is supported.  (ie: first API call
initialization).

Kurt