I wrote a Design Document which describes the policy how to design the library, please add comments. It also shows some changes of the new development api.
Elektra Design Document ======================= This document describes the design of the c-api and gives hints for binding writers. It does not aim to backend writers because this detail is hidden from the programmer. Versions and Compatibility ========================== Compatibility will be the aim of elektra after 1.0. 1.x will be just bug fixes and corrected beheaviour and documentation. y.0 will show that new features are added, but this should not happen too often. However, Applications written for elektra 1.0 should always work and build together with any elektra released in the feature. But before we reach a 1.0 state, we must perceive that a mature, easy, clean and yet minimalistic powerful library is required. This needs always changes where something not-perfect is found. Only a large testing framework, many ported apps and backends can exhibit that the goal is archieved. Memory Management ================= Elektra manages memory itself. No free must be required, which was not allocated by the programmer himself. This avoids that free is forgotten, makes the API more beginner-friendly. In addition to all that malloc and free must have the same libc version. malloc in a library linked against another libc, but freed by the application could lead to hard to find bugs. Some calls have a opposite call to get the structure freed again: KDBHandle * kdbOpen(); will need the function: int kdbClose(KDBHandle *handle); to get rid of the resources again. It maybe also shut down connections, so it really must be called at the end of the program. Key *keyNew(const char *keyName, ...); int keyDel(Key *key); KeySet *ksNew(); int ksDel(KeySet *ks); These 2 pairs just malloc what is necessary and free it again. There are more mallocs then just the KDBHandle, Key and KeySet structures. Name, Value, Comment can't be handled as easy, because elektra does not provide a string library. There are 2 ways to access it, showed on the Comment example: While char *keyComment(const Key *key); just returns the comment and does not allow any change of size of the comment. ssize_t keyGetCommentSize(const Key *key); ssize_t keyGetComment(const Key *key, char *returnedDesc, size_t maxSize); This pair is necessary because '\0' might be part of the string, but C does not allowes it. Using these functions you are on the safe side, even Comment and String does not contain '\0' in fact. Value, String or Binary ======================= Some confusion is about value, string or binary. Value is just a name which does not specify if it is a string or binary. String is a char array, with a terminating '\0', but Binary is a void array, not terminated by '\0'. But please use the appendant *Size functions, to be not dependend on that internal facts. Return Value ============ There are many different types of return values. What they have in common is there error behaviour. Every function must return -1 on error if it returns Integers (like int, ssize_t). If they return a pointer, 0 will show the error. This can't be used for Integers, because 0 might be a valid size. Error Handling ============== Error handling is done with errno. There was lot of discussion about why not using a own variable. This is not possible, because of thread safety. Another thread using elektra could see wrong error codes. The other idea would be to store the variable in KDBHandle. This would be possible, but it would force us to pass the KDBHandle to *every* function in elektra, which is not accommodate for storing the error code. Maybe we will use a thread safe variable once a day, which is very difficult because you must support all thread models available, so please use kdbGetErrno if you want the errno for elektra. Naming ====== All Names begin with kdb, ks or kdb. The words are written together with large letters for seperation. This leads to short names, but might be not as good to read. Its more the c++ way, like the *New functions *Del. const ===== Where possible the functions should use const for parameters. Where Key or KeySet is not modified, const is used. For return values no const is used, its more disturbing then have any positive effect. The only exceptions are: In special: const char *keyName(const Key *key); const char *keyBaseName(const Key *key); const char *keyComment(const Key *key); const void *keyValue(const Key *key); These functions are really not thought to get something and change anything! Elektra will lose the knowledge if these keys are synchronized or not. So they are marked const, and you must not cast that away. thank you Markus Raab ------------------------------------------------------------------------- Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV _______________________________________________ Registry-list mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/registry-list
