current/doc/Server.txt

operating an OpenIsis server with one or more threads


*       server interface

From the OpenIsis API, all db IO calls can be redirected to a server.
However, only the basic database access is done by the server,
convenience functions like formatting are processed locally.
There would be no point in processing stream IO or record utilities remotely.
While database control calls are generally NOT accessible via the wire,
some of them have counterparts for managing the server session.


*       the multisession server

A multisession server deploys multiple threads to process requests
from multiple sessions in parallel. Each session occupies at most one
thread at a time (and, of course, vice versa), but threads and sessions
are not (necessarily) bound to each other during their lifetime.


Rather there is a dispatcher monitoring all session's input streams
and allocating threads as needed.
However, there is one thread bound to the default session,
which is thus not subject to dispatching.


* principles of communication

The server communicates with it's clients by sending messages over streams.
While the server's IO multiplexer engine is designed to allow for a variety
of applications, the database server API's messages are OpenIsis records.
There are field numbers and subfield codes assigned to each
parameter of a request. Parameters which are records themselves
are encapsulated transparently, i.e. by giving their length in advance.


In basic communication mode (i.e. not using a wrapper protocol like HTTP),
these records are then transmitted as lines consisting of a field number
printed using ASCII decimal digits, followed by a TAB, followed
by the field's contents and a newline (NL).
Each NL within the contents is converted to NL-TAB and
on the receiving side, each line starting with a TAB is treated
as continuation of the previous field.
Transmission ends with an empty line.


*       session streams

The streams connected to a session are usually backed by some kind of socket.
Since requests carry a session id,
sessions may be multiplexed onto one or more sockets,
possibly using one connection per request or even UDP datagrams.
Each response, however, is sent on the socket where the corresponding
request was received on and in the order request went in.


The default session is always bound 1:1 to a communication channel,
not subject to multiplexing
(i.e. session id 0 is implied by and allowed only on this channel).
Yet this channel may be a named pipe or localhost or unix socket,
which does not have a permanent client connection
and may be controlled by the multiplexer.


Typically, it's client side is a Tcl belonging to the same process,
either a tclsh as controller of a multisession server
or a wish as the sole client within a standalone application.
On Unix, this server thread is most easily connected to by
a pair of pipes (using Tcl_CreateFileHandler).
Under Windows, things are much more complicated ...

In general, the marshalling to a stream might of course
be skipped when using inter thread communication.
Either side might just prepare the record to the session's
request or response buffer, resp., and then ring some bell
like Tcl_ThreadQueueEvent and Tcl_ThreadAlert.


*       the server's heart

A server enters multisession mode by starting up the multiplexer.
The multiplexer may run in a separate thread or in the same
one as the default session, depending on the means by which
the default session is connected to it's controlling input.
The multiplexer starts up some number of worker threads,
listens on a TCP port and then sits in a loop
-       selecting the server socket and all already open connections
-       accepting new connections
-       writing available responses to writable sockets
-       reading the first few bytes from readable sockets
        (from which it not already has a partly request)
        to check for session ids (SID).
        If a request does not start with a SID,
        it belongs to (i.e. optionally creates) the session bound to this socket.
-       deciding from which (readable) sockets more should be read.
        Input belonging to sessions already in process is left alone.
-       reading available input, checking for complete requests
-       if the multiplexer handles default session's input and there
        is a request available, it is processed in this thread
-       queing complete requests for processing
-       checking the response queue for completed requests,
        collecting responses and freeing threads.
        Requests producing large amounts of output
        (similar to piggybacked Z39.50 present requests)
        may create partly responses before beeing finished.
-       assigning from the request queue to available worker threads

Note that this multiplexer architecture is in no way special
to OpenIsis database access, but suited and intended to drive
a session oriented, but otherwise multi-purpose application server.

In the context of serving an OpenIsis database,
the server is essentially stateless.
It may at any time decide to drop inactive sessions,
unless it was talked into (configured for) promising to keep result sets.


*       the single threaded server

The single threaded version of the server has only one thread
and typically only one session, i.e. the default session.

Note that single threaded means there is only one thread accessing
the database. There may still be other threads in the process,
e.g. to care for the user interface.


A single session server is not very useful in itself.
However, it allows some user interface to be programmed using
the server API regardless of whether a local or remote DB is accessed,
and to discouple even local processing from the UI.

Another variant of a single threaded server is multisession,
i.e. running a session multiplexer, but not dispatching jobs
to a worker thread pool.
This may be useful as minimal server on platforms with no
or broken multithreading support, especially Win 9x/Me
(which lacks the NT call SignalObjectAndWait).


---
        $Id: Server.txt,v 1.3 2003/02/14 17:30:33 kripke Exp $
1	dpavlin	237	operating an OpenIsis server with one or more threads
2
3
4			* server interface
5
6			From the OpenIsis API, all db IO calls can be redirected to a server.
7			However, only the basic database access is done by the server,
8			convenience functions like formatting are processed locally.
9			There would be no point in processing stream IO or record utilities remotely.
10			While database control calls are generally NOT accessible via the wire,
11			some of them have counterparts for managing the server session.
12
13
14			* the multisession server
15
16			A multisession server deploys multiple threads to process requests
17			from multiple sessions in parallel. Each session occupies at most one
18			thread at a time (and, of course, vice versa), but threads and sessions
19			are not (necessarily) bound to each other during their lifetime.
20
21
22			Rather there is a dispatcher monitoring all session's input streams
23			and allocating threads as needed.
24			However, there is one thread bound to the default session,
25			which is thus not subject to dispatching.
26
27
28			* principles of communication
29
30			The server communicates with it's clients by sending messages over streams.
31			While the server's IO multiplexer engine is designed to allow for a variety
32			of applications, the database server API's messages are OpenIsis records.
33			There are field numbers and subfield codes assigned to each
34			parameter of a request. Parameters which are records themselves
35			are encapsulated transparently, i.e. by giving their length in advance.
36
37
38			In basic communication mode (i.e. not using a wrapper protocol like HTTP),
39			these records are then transmitted as lines consisting of a field number
40			printed using ASCII decimal digits, followed by a TAB, followed
41			by the field's contents and a newline (NL).
42			Each NL within the contents is converted to NL-TAB and
43			on the receiving side, each line starting with a TAB is treated
44			as continuation of the previous field.
45			Transmission ends with an empty line.
46
47
48			* session streams
49
50			The streams connected to a session are usually backed by some kind of socket.
51			Since requests carry a session id,
52			sessions may be multiplexed onto one or more sockets,
53			possibly using one connection per request or even UDP datagrams.
54			Each response, however, is sent on the socket where the corresponding
55			request was received on and in the order request went in.
56
57
58			The default session is always bound 1:1 to a communication channel,
59			not subject to multiplexing
60			(i.e. session id 0 is implied by and allowed only on this channel).
61			Yet this channel may be a named pipe or localhost or unix socket,
62			which does not have a permanent client connection
63			and may be controlled by the multiplexer.
64
65
66			Typically, it's client side is a Tcl belonging to the same process,
67			either a tclsh as controller of a multisession server
68			or a wish as the sole client within a standalone application.
69			On Unix, this server thread is most easily connected to by
70			a pair of pipes (using Tcl_CreateFileHandler).
71			Under Windows, things are much more complicated ...
72
73			In general, the marshalling to a stream might of course
74			be skipped when using inter thread communication.
75			Either side might just prepare the record to the session's
76			request or response buffer, resp., and then ring some bell
77			like Tcl_ThreadQueueEvent and Tcl_ThreadAlert.
78
79
80			* the server's heart
81
82			A server enters multisession mode by starting up the multiplexer.
83			The multiplexer may run in a separate thread or in the same
84			one as the default session, depending on the means by which
85			the default session is connected to it's controlling input.
86			The multiplexer starts up some number of worker threads,
87			listens on a TCP port and then sits in a loop
88			- selecting the server socket and all already open connections
89			- accepting new connections
90			- writing available responses to writable sockets
91			- reading the first few bytes from readable sockets
92			(from which it not already has a partly request)
93			to check for session ids (SID).
94			If a request does not start with a SID,
95			it belongs to (i.e. optionally creates) the session bound to this socket.
96			- deciding from which (readable) sockets more should be read.
97			Input belonging to sessions already in process is left alone.
98			- reading available input, checking for complete requests
99			- if the multiplexer handles default session's input and there
100			is a request available, it is processed in this thread
101			- queing complete requests for processing
102			- checking the response queue for completed requests,
103			collecting responses and freeing threads.
104			Requests producing large amounts of output
105			(similar to piggybacked Z39.50 present requests)
106			may create partly responses before beeing finished.
107			- assigning from the request queue to available worker threads
108
109			Note that this multiplexer architecture is in no way special
110			to OpenIsis database access, but suited and intended to drive
111			a session oriented, but otherwise multi-purpose application server.
112
113			In the context of serving an OpenIsis database,
114			the server is essentially stateless.
115			It may at any time decide to drop inactive sessions,
116			unless it was talked into (configured for) promising to keep result sets.
117
118
119			* the single threaded server
120
121			The single threaded version of the server has only one thread
122			and typically only one session, i.e. the default session.
123
124			Note that single threaded means there is only one thread accessing
125			the database. There may still be other threads in the process,
126			e.g. to care for the user interface.
127
128
129			A single session server is not very useful in itself.
130			However, it allows some user interface to be programmed using
131			the server API regardless of whether a local or remote DB is accessed,
132			and to discouple even local processing from the UI.
133
134			Another variant of a single threaded server is multisession,
135			i.e. running a session multiplexer, but not dispatching jobs
136			to a worker thread pool.
137			This may be useful as minimal server on platforms with no
138			or broken multithreading support, especially Win 9x/Me
139			(which lacks the NT call SignalObjectAndWait).
140
141
142			---
143			$Id: Server.txt,v 1.3 2003/02/14 17:30:33 kripke Exp $