/[webpac]/openisis/current/doc/Api.txt
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Contents of /openisis/current/doc/Api.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 237 - (show annotations)
Mon Mar 8 17:43:12 2004 UTC (16 years, 7 months ago) by dpavlin
File MIME type: text/plain
File size: 5068 byte(s)
initial import of openisis 0.9.0 vendor drop

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 $

  ViewVC Help
Powered by ViewVC 1.1.26