/[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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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 $

  ViewVC Help
Powered by ViewVC 1.1.26