+++ /dev/null
-Note: the follwing list might be somewhat out of date,
-but probably you get the picture.
-
-There is a major overhaul of the API from 0.8.7 to 0.9 underway:
-The concept of a session is introduced to allow for safe
-and efficient multithreaded concurrency.
-Nearly every API call has a Session parameter,
-and basic system services like memory allocation
-and stdio are bound to sessions.
-All but the control calls may be called from any session in any thread
-(but from no single session in more than one thread).
-All but the database calls will moreover execute in parallel
-without any interlocking.
-
-
-The new Api is organised in the following sections:
-- M et al: memory & utilities
-- S: session & stream IO
-- R: record
-- D: db IO
-- F: fdt utilities
-- N: network stubs
-- C: control
- the control calls are the only calls w/o a Session parameter,
- since they MUST NOT be called from any but the default session
-
-
-There is also an
-> Concurrency overview
-on concurrency and synchronization in OpenIsis.
-
-* naming conventions
-
-All calls besides some common utilities start with
-the letter of their respective section followed by
-an uppercase letter.
-Functions are mixed case with initial lower,
-types are mixed case with initial upper and macros
-and enum values are all upper, variables are all lower case.
-
-For convenience, there are two versions of the "OpenIsis namespace":
-- in the official version as given by openisis.h,
- every call starts with openIsis followed by an uppercase letter.
- Every type starts with OpenIsis, and every macro with OPENISIS_.
-- inside the "OpenIsis namespace", as given by loi.h,
- the leading openIsis is cut of to avoid cluttering,
- while preserving the case rules.
-
-As an example, OpenIsisSession and openIsisMAlloc may be used
-as Session and mAlloc with loi.h.
-
-* transition
-
-The old (0.8.7) interface is retained via macros refering to the default
-session. During the transition process, some calls will also get
-a redesign with respect to other parameters,
-for example, by replacing an argv/argc list by a Record.
-It should, however, be reasonably safe to refer to the old interface.
-
-The following list is neither complete nor fixed,
-but rather a roadmap.
-The mapping of old to new calls is not always one-to-one.
-
-* M et al: memory & utilities
-
-$
-mAlloc
-mFree
-mDup
-
-toHtml openIsis2Html
-utf8Chk openIsisValidUTF8
-$
-
-* S: session & stream IO
-
-$
-Session OpenIsisSession
-Stream OpenIsisStream
-sMsg openIsisMsg
-sOpen openIsisSopen
-sGets openIsisSGets
-sReadln openIsisSReadln
-sGetr openIsisReadStream
-$
-
-* R: record
-
-$
-Field OpenIsisField
-Rec OpenIsisRec
-rSplit openIsisReadField
-rDup openIsisClone
-rMsg openIsisPrintf
-rFmt openIsisFmt
-rSel (openIsisFmt)
-$
-
-* D: db IO
-
-$
-dRead openIsisReadRow
-dRaw openIsisReadRaw
-dFmt openIsisRead
-dWrite openIsisWrite
-dMaxId openIsisMaxRowid
-dScan openIsisScan
-dQuery openIsisQuery
-dWhere (openIsisQuery)
-dTerm openIsisTerm
-dIndex (openIsisTerm)
-dIndex openIsisIdxLoop
-$
-
-
-* C: control
-
-$
-cInit openIsisInit
-cOpen
-cClose
-cSet openIsisLog
-cSession openIsisSesGet
-cDOpen openIsisOpen
-cDCheck openIsisCheck
-cDClose openIsisClose
-cXOpen openIsisIdxOpen
-cXBadd openIsisIdxAdd
-$
-
-In the multithreaded server, sessions are actually
-created by the multiplexer, which need not be in the same
-thread as the default session.
-
-
-*modules library modules
-
-This, too, describes the should-be rather than current state:
-- uti: Memory and other basic utilities
-- io: internal operating system access
-- ses: Sessions and Streams
-- fdt: fdt utils and global system fdts
-- fmt: the rSel formatting
-- rec: other R tools
-- stb: Stubs
-- str: internal structure
-- cs: character sets
-- bt: index X access
-- qry: the dWhere query
-- db: most Db and Control
-
-
-* initialization order:
-
-- cOpen: default cs
-- cOpen: io fd 0-2 (windoze)
-- cOpen: default session w/o params, pulls memory
-- cOpen: default session w/ params
-- cDOpen: cOpen
-- cDOpen: str
-- cDOpen: database
-- cSession: other sessions
-
-*ISOC a note on ISO C
-
-It became obvious that there is little we can use from the system,
-partly due to compatibility problems,
-partly due to the multithreaded environment we need.
-stdio doesn't work at all and malloc heap management needs to be wrapped.
-
-Thus the use of libc (at least outside of lio.c) is limited
-more or less to string.h (for strlen, memcpy, memcmp).
-I found that in many places the sole reason to include any system header,
-namely stddef.h, is NULL and size_t.
-
-
-We require an ISO C (a.k.a. ANSI C a.k.a. STDC) compiler anyway.
-Studying the standard, I found that the use of NULL is completely
-obsolete in ISO C, since the relation between "NULL pointers",
-the 0 literal and conditional expressions is well defined _by the compiler_.
-What stddef.h does, is only _suggested_, and looking at gcc's stddef.h,
-it is a rather desperate attempt to arrange for all that
-should be _despite_ any system environment.
-The same holds for size_t, ssize_t, off_t, ptrdiff_t, you name it:
-it's a broken interface to a broken "standard" library,
-so we don't use it anymore.
-
-
----
- $Id: Api.txt,v 1.8 2003/05/01 10:06:32 mawag Exp $
projects / webpac / blobdiff