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 $ |