current/doc/Api.txt

Note: the follwing list might be somewhat out of date,
but probably you get the picture.

There is a major overhaul of the API from 0.8.7 to 0.9 underway:
The concept of a session is introduced to allow for safe
and efficient multithreaded concurrency.
Nearly every API call has a Session parameter,
and basic system services like memory allocation
and stdio are bound to sessions.
All but the control calls may be called from any session in any thread
(but from no single session in more than one thread).
All but the database calls will moreover execute in parallel
without any interlocking.


The new Api is organised in the following sections:
-       M et al: memory & utilities
-       S: session & stream IO
-       R: record
-       D: db IO
-       F: fdt utilities
-       N: network stubs
-       C: control
        the control calls are the only calls w/o a Session parameter,
        since they MUST NOT be called from any but the default session


There is also an
>       Concurrency     overview
on concurrency and synchronization in OpenIsis.

*       naming conventions

All calls besides some common utilities start with
the letter of their respective section followed by
an uppercase letter.
Functions are mixed case with initial lower,
types are mixed case with initial upper and macros
and enum values are all upper, variables are all lower case.

For convenience, there are two versions of the "OpenIsis namespace":
-       in the official version as given by openisis.h,
        every call starts with openIsis followed by an uppercase letter.
        Every type starts with OpenIsis, and every macro with OPENISIS_.
-       inside the "OpenIsis namespace", as given by loi.h,
        the leading openIsis is cut of to avoid cluttering,
        while preserving the case rules.

As an example, OpenIsisSession and openIsisMAlloc may be used
as Session and mAlloc with loi.h.

*       transition

The old (0.8.7) interface is retained via macros refering to the default
session. During the transition process, some calls will also get
a redesign with respect to other parameters,
for example, by replacing an argv/argc list by a Record.
It should, however, be reasonably safe to refer to the old interface.

The following list is neither complete nor fixed,
but rather a roadmap.
The mapping of old to new calls is not always one-to-one.

*       M et al: memory & utilities

$
mAlloc
mFree
mDup

toHtml  openIsis2Html
utf8Chk openIsisValidUTF8
$

*       S: session & stream IO

$
Session OpenIsisSession
Stream  OpenIsisStream
sMsg    openIsisMsg
sOpen   openIsisSopen
sGets   openIsisSGets
sReadln openIsisSReadln
sGetr   openIsisReadStream
$

*       R: record

$
Field   OpenIsisField
Rec     OpenIsisRec
rSplit  openIsisReadField
rDup    openIsisClone
rMsg    openIsisPrintf
rFmt    openIsisFmt
rSel    (openIsisFmt)
$

*       D: db IO

$
dRead   openIsisReadRow
dRaw    openIsisReadRaw
dFmt    openIsisRead
dWrite  openIsisWrite
dMaxId  openIsisMaxRowid
dScan   openIsisScan
dQuery  openIsisQuery
dWhere  (openIsisQuery)
dTerm   openIsisTerm
dIndex  (openIsisTerm)
dIndex  openIsisIdxLoop
$


*       C: control

$
cInit   openIsisInit
cOpen
cClose
cSet    openIsisLog
cSession        openIsisSesGet
cDOpen  openIsisOpen
cDCheck openIsisCheck
cDClose openIsisClose
cXOpen  openIsisIdxOpen
cXBadd  openIsisIdxAdd
$

In the multithreaded server, sessions are actually
created by the multiplexer, which need not be in the same
thread as the default session.


*modules        library modules

This, too, describes the should-be rather than current state:
-       uti:    Memory and other basic utilities
-       io:     internal operating system access
-       ses:    Sessions and Streams
-       fdt:    fdt utils and global system fdts
-       fmt:    the rSel formatting
-       rec:    other R tools
-       stb:    Stubs
-       str:    internal structure
-       cs:     character sets
-       bt:     index X access
-       qry:    the dWhere query
-       db:     most Db and Control


*       initialization order:

-       cOpen: default cs
-       cOpen: io fd 0-2 (windoze)
-       cOpen: default session w/o params, pulls memory
-       cOpen: default session w/ params
-       cDOpen: cOpen
-       cDOpen: str
-       cDOpen: database
-       cSession: other sessions

*ISOC   a note on ISO C

It became obvious that there is little we can use from the system,
partly due to compatibility problems,
partly due to the multithreaded environment we need.
stdio doesn't work at all and malloc heap management needs to be wrapped.

Thus the use of libc (at least outside of lio.c) is limited
more or less to string.h (for strlen, memcpy, memcmp).
I found that in many places the sole reason to include any system header,
namely stddef.h, is NULL and size_t.


We require an ISO C (a.k.a. ANSI C a.k.a. STDC) compiler anyway.
Studying the standard, I found that the use of NULL is completely
obsolete in ISO C, since the relation between "NULL pointers",
the 0 literal and conditional expressions is well defined _by the compiler_.
What stddef.h does, is only _suggested_, and looking at gcc's stddef.h,
it is a rather desperate attempt to arrange for all that
should be _despite_ any system environment.
The same holds for size_t, ssize_t, off_t, ptrdiff_t, you name it:
it's a broken interface to a broken "standard" library,
so we don't use it anymore.


---
        $Id: Api.txt,v 1.8 2003/05/01 10:06:32 mawag Exp $
1	Note: the follwing list might be somewhat out of date,
2	but probably you get the picture.
3
4	There is a major overhaul of the API from 0.8.7 to 0.9 underway:
5	The concept of a session is introduced to allow for safe
6	and efficient multithreaded concurrency.
7	Nearly every API call has a Session parameter,
8	and basic system services like memory allocation
9	and stdio are bound to sessions.
10	All but the control calls may be called from any session in any thread
11	(but from no single session in more than one thread).
12	All but the database calls will moreover execute in parallel
13	without any interlocking.
14
15
16	The new Api is organised in the following sections:
17	- M et al: memory & utilities
18	- S: session & stream IO
19	- R: record
20	- D: db IO
21	- F: fdt utilities
22	- N: network stubs
23	- C: control
24	the control calls are the only calls w/o a Session parameter,
25	since they MUST NOT be called from any but the default session
26
27
28	There is also an
29	> Concurrency overview
30	on concurrency and synchronization in OpenIsis.
31
32	* naming conventions
33
34	All calls besides some common utilities start with
35	the letter of their respective section followed by
36	an uppercase letter.
37	Functions are mixed case with initial lower,
38	types are mixed case with initial upper and macros
39	and enum values are all upper, variables are all lower case.
40
41	For convenience, there are two versions of the "OpenIsis namespace":
42	- in the official version as given by openisis.h,
43	every call starts with openIsis followed by an uppercase letter.
44	Every type starts with OpenIsis, and every macro with OPENISIS_.
45	- inside the "OpenIsis namespace", as given by loi.h,
46	the leading openIsis is cut of to avoid cluttering,
47	while preserving the case rules.
48
49	As an example, OpenIsisSession and openIsisMAlloc may be used
50	as Session and mAlloc with loi.h.
51
52	* transition
53
54	The old (0.8.7) interface is retained via macros refering to the default
55	session. During the transition process, some calls will also get
56	a redesign with respect to other parameters,
57	for example, by replacing an argv/argc list by a Record.
58	It should, however, be reasonably safe to refer to the old interface.
59
60	The following list is neither complete nor fixed,
61	but rather a roadmap.
62	The mapping of old to new calls is not always one-to-one.
63
64	* M et al: memory & utilities
65
66	$
67	mAlloc
68	mFree
69	mDup
70
71	toHtml openIsis2Html
72	utf8Chk openIsisValidUTF8
73	$
74
75	* S: session & stream IO
76
77	$
78	Session OpenIsisSession
79	Stream OpenIsisStream
80	sMsg openIsisMsg
81	sOpen openIsisSopen
82	sGets openIsisSGets
83	sReadln openIsisSReadln
84	sGetr openIsisReadStream
85	$
86
87	* R: record
88
89	$
90	Field OpenIsisField
91	Rec OpenIsisRec
92	rSplit openIsisReadField
93	rDup openIsisClone
94	rMsg openIsisPrintf
95	rFmt openIsisFmt
96	rSel (openIsisFmt)
97	$
98
99	* D: db IO
100
101	$
102	dRead openIsisReadRow
103	dRaw openIsisReadRaw
104	dFmt openIsisRead
105	dWrite openIsisWrite
106	dMaxId openIsisMaxRowid
107	dScan openIsisScan
108	dQuery openIsisQuery
109	dWhere (openIsisQuery)
110	dTerm openIsisTerm
111	dIndex (openIsisTerm)
112	dIndex openIsisIdxLoop
113	$
114
115
116	* C: control
117
118	$
119	cInit openIsisInit
120	cOpen
121	cClose
122	cSet openIsisLog
123	cSession openIsisSesGet
124	cDOpen openIsisOpen
125	cDCheck openIsisCheck
126	cDClose openIsisClose
127	cXOpen openIsisIdxOpen
128	cXBadd openIsisIdxAdd
129	$
130
131	In the multithreaded server, sessions are actually
132	created by the multiplexer, which need not be in the same
133	thread as the default session.
134
135
136	*modules library modules
137
138	This, too, describes the should-be rather than current state:
139	- uti: Memory and other basic utilities
140	- io: internal operating system access
141	- ses: Sessions and Streams
142	- fdt: fdt utils and global system fdts
143	- fmt: the rSel formatting
144	- rec: other R tools
145	- stb: Stubs
146	- str: internal structure
147	- cs: character sets
148	- bt: index X access
149	- qry: the dWhere query
150	- db: most Db and Control
151
152
153	* initialization order:
154
155	- cOpen: default cs
156	- cOpen: io fd 0-2 (windoze)
157	- cOpen: default session w/o params, pulls memory
158	- cOpen: default session w/ params
159	- cDOpen: cOpen
160	- cDOpen: str
161	- cDOpen: database
162	- cSession: other sessions
163
164	*ISOC a note on ISO C
165
166	It became obvious that there is little we can use from the system,
167	partly due to compatibility problems,
168	partly due to the multithreaded environment we need.
169	stdio doesn't work at all and malloc heap management needs to be wrapped.
170
171	Thus the use of libc (at least outside of lio.c) is limited
172	more or less to string.h (for strlen, memcpy, memcmp).
173	I found that in many places the sole reason to include any system header,
174	namely stddef.h, is NULL and size_t.
175
176
177	We require an ISO C (a.k.a. ANSI C a.k.a. STDC) compiler anyway.
178	Studying the standard, I found that the use of NULL is completely
179	obsolete in ISO C, since the relation between "NULL pointers",
180	the 0 literal and conditional expressions is well defined _by the compiler_.
181	What stddef.h does, is only _suggested_, and looking at gcc's stddef.h,
182	it is a rather desperate attempt to arrange for all that
183	should be _despite_ any system environment.
184	The same holds for size_t, ssize_t, off_t, ptrdiff_t, you name it:
185	it's a broken interface to a broken "standard" library,
186	so we don't use it anymore.
187
188
189	---
190	$Id: Api.txt,v 1.8 2003/05/01 10:06:32 mawag Exp $