1 Note: the follwing list might be somewhat out of date,
2 but probably you get the picture.
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.
16 The new Api is organised in the following sections:
17 - M et al: memory & utilities
18 - S: session & stream IO
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
29 > Concurrency overview
30 on concurrency and synchronization in OpenIsis.
34 All calls besides some common utilities start with
35 the letter of their respective section followed by
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.
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.
49 As an example, OpenIsisSession and openIsisMAlloc may be used
50 as Session and mAlloc with loi.h.
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.
60 The following list is neither complete nor fixed,
62 The mapping of old to new calls is not always one-to-one.
64 * M et al: memory & utilities
72 utf8Chk openIsisValidUTF8
75 * S: session & stream IO
78 Session OpenIsisSession
83 sReadln openIsisSReadln
84 sGetr openIsisReadStream
92 rSplit openIsisReadField
102 dRead openIsisReadRow
106 dMaxId openIsisMaxRowid
109 dWhere (openIsisQuery)
111 dIndex (openIsisTerm)
112 dIndex openIsisIdxLoop
123 cSession openIsisSesGet
125 cDCheck openIsisCheck
126 cDClose openIsisClose
127 cXOpen openIsisIdxOpen
128 cXBadd openIsisIdxAdd
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.
136 *modules library modules
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
146 - str: internal structure
149 - qry: the dWhere query
150 - db: most Db and Control
153 * initialization order:
156 - cOpen: io fd 0-2 (windoze)
157 - cOpen: default session w/o params, pulls memory
158 - cOpen: default session w/ params
162 - cSession: other sessions
164 *ISOC a note on ISO C
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.
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.
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.
190 $Id: Api.txt,v 1.8 2003/05/01 10:06:32 mawag Exp $