1 |
dpavlin |
237 |
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 $ |