current/doc/PHP.txt

considerations on the design of a PHP interface

This paper is based on the requirements of
>       Concurrency


*       why not to export sessions

From the C-API's point of view, the use of sessions is a MUST
in a multithreaded environment, which PHP may be. 
This, however, is the server-side of the PHP engine.
The PHP page, as seen by the programmer, is a client to the database:
it does NOT handle multiple requests, but one!

In other words, the page is already executing within the context of
a given request, including a given thread.
Since a request is not meant to operate on several sessions,
but rather has one session as an attribute of it's context,
nothing would be gained by making the session visible ("export")
to the PHP programmer by calls like read(ses,...) or ses->read(...).


Moreover, the currently most used environments, i.e. MP Apache 1.x/Unix
and some Windoze boxes, do not allow/require the use of multiple sessions,
anyway.

Finally, the only reason to explicitly select a session based on a user's
session id, would be to access this session's state as #1-style result sets
or authentication information. Both will not be implemented in the near
future and both will rarely be needed in web environments.
Yet, it might be made available when needed by means of an additional
call that "selects" that session as the one to be associated with the
request context.


*       strategy

Therefore, I would suggest the following strategy:
-       In the first step, stick to the default session by using a static
        session variable like openisis_ses0 and auto-initializing it like
        the OPENISIS_SES0 macro does.
-       For the MP version register a function using register_shutdown_function
        (is there a corresponding C-API to register a C function ?)
        that closes all open DBs in order to release their flocks.
        (Berlin will provide such a "close all").
-       On Windoze and Apache 2, make sure to actually run single-threaded
        by using EnterCriticalSection/pthread_mutex_lock
        on a static CRITICAL_SECTION/PTHREAD_MUTEX_INITIALIZER
        and leaving/unlocking it in a registered shutdown_function
-       Some day, in a better age, replace the static session variable
        with a thread specific one by using pthread_key_create/pthread_setspecific
        or maybe PHP's TSRM.

C.f. man pthread_mutex_lock, 
>       http://msdn.microsoft.com/library/en-us/dllproc/base/critical_section_objects.asp       critical Windoze


*       notes

-       is there a call in the PHP API that can be relied upon
        to be the first one used, in order to do initialization?
        Probably opening a DB?
-       In the MT version, closing databases is not enforced,
        thus successive requests will open already opened databases.
        This is ok with the C-API's DOpen, which will happily return
        the same handle.
-       Once additional worker sessions/threads are supported,
        we'll need additional open/close calls, which do neither
        actually open or close a database, but access and release
        (and possibly flush). The MT and MP usage could then be made
        to look very similarm with details governed by a few config
        settings.

---
        $Id: PHP.txt,v 1.1 2003/02/13 20:36:23 kripke Exp $
1	dpavlin	237	considerations on the design of a PHP interface
2
3			This paper is based on the requirements of
4			> Concurrency
5
6
7			* why not to export sessions
8
9			From the C-API's point of view, the use of sessions is a MUST
10			in a multithreaded environment, which PHP may be.
11			This, however, is the server-side of the PHP engine.
12			The PHP page, as seen by the programmer, is a client to the database:
13			it does NOT handle multiple requests, but one!
14
15			In other words, the page is already executing within the context of
16			a given request, including a given thread.
17			Since a request is not meant to operate on several sessions,
18			but rather has one session as an attribute of it's context,
19			nothing would be gained by making the session visible ("export")
20			to the PHP programmer by calls like read(ses,...) or ses->read(...).
21
22
23			Moreover, the currently most used environments, i.e. MP Apache 1.x/Unix
24			and some Windoze boxes, do not allow/require the use of multiple sessions,
25			anyway.
26
27			Finally, the only reason to explicitly select a session based on a user's
28			session id, would be to access this session's state as #1-style result sets
29			or authentication information. Both will not be implemented in the near
30			future and both will rarely be needed in web environments.
31			Yet, it might be made available when needed by means of an additional
32			call that "selects" that session as the one to be associated with the
33			request context.
34
35
36			* strategy
37
38			Therefore, I would suggest the following strategy:
39			- In the first step, stick to the default session by using a static
40			session variable like openisis_ses0 and auto-initializing it like
41			the OPENISIS_SES0 macro does.
42			- For the MP version register a function using register_shutdown_function
43			(is there a corresponding C-API to register a C function ?)
44			that closes all open DBs in order to release their flocks.
45			(Berlin will provide such a "close all").
46			- On Windoze and Apache 2, make sure to actually run single-threaded
47			by using EnterCriticalSection/pthread_mutex_lock
48			on a static CRITICAL_SECTION/PTHREAD_MUTEX_INITIALIZER
49			and leaving/unlocking it in a registered shutdown_function
50			- Some day, in a better age, replace the static session variable
51			with a thread specific one by using pthread_key_create/pthread_setspecific
52			or maybe PHP's TSRM.
53
54			C.f. man pthread_mutex_lock,
55			> http://msdn.microsoft.com/library/en-us/dllproc/base/critical_section_objects.asp critical Windoze
56
57
58			* notes
59
60			- is there a call in the PHP API that can be relied upon
61			to be the first one used, in order to do initialization?
62			Probably opening a DB?
63			- In the MT version, closing databases is not enforced,
64			thus successive requests will open already opened databases.
65			This is ok with the C-API's DOpen, which will happily return
66			the same handle.
67			- Once additional worker sessions/threads are supported,
68			we'll need additional open/close calls, which do neither
69			actually open or close a database, but access and release
70			(and possibly flush). The MT and MP usage could then be made
71			to look very similarm with details governed by a few config
72			settings.
73
74			---
75			$Id: PHP.txt,v 1.1 2003/02/13 20:36:23 kripke Exp $