From fc78adce8146c63bca60afd8eb377c4e5cb3e754 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonathan=20Sch=C3=B6bel?= <jonathan@xn--schbel-yxa.info> Date: Sun, 8 Oct 2023 14:39:45 +0200 Subject: [PATCH] docs: collect commit messages #3 Up to (and including) commit e572e78b76a53cbfd24946e2a0d7f1320b5a9875 'renamed macros' --- docs/commit_messages.txt | 79 +++++++++++++++++++++++++++++++++++++--- sefht.geany | 2 +- 2 files changed, 75 insertions(+), 6 deletions(-) diff --git a/docs/commit_messages.txt b/docs/commit_messages.txt index d6505a1..4cd6f96 100644 --- a/docs/commit_messages.txt +++ b/docs/commit_messages.txt @@ -45,14 +45,53 @@ Compilation: is to test for the internal state. Error handling: - Error handling is done by passing an Error structure as an - inout parameter to functions that can fail on runtime - predictably. This parameter is always the last one. Methods, - where there is no error, that can be detected on runtime, - don't have an error parameter. + Error handling is done by the status structure. The name was + chosen in favour of error, because status is also set + independently whether an error has occurred. + The structure must be allocated by the caller, + because allocation errors may need to be handled, and in such a + case, it is unlikely, that it is possible to allocate memory. + Every function, that can fail predictably on runtime, supports + passing a pointer to a status structure as the last parameter. + Functions that can't fail detectably, doesn't have the parameter. + + The structure contains an error type, the errno, the filename, + the function name, the line number and a message. + There are the following error types: + undefined: only needed to test, whether a function properly sets + the status parameter, might be removed in the future. + SUCCESS: no error has occurred. + E_ALLOC: allocation failure: malloc/realloc/calloc or strdup etc. + E_DOMAIN: Something is not representable due to a chosen type. + For example, there are more elements in an array, then + the index type supports. + E_VALUE: Some parameter had an erroneous value. For example, + an index out of bounds or a non existing reference. + E_STATE: Something is unfulfillable, due to some constraint. + E_BUG: Some unconsistent state was encountered. This always + indicates some bug in the library, not in the user + program, for this E_VALUE or E_STATE are used. However, + it might be caused by the user program manipulating + internals. + The filename, function name and line number point to the file, + where the error has occurred in the first place. This might not + be the function, that is called from the outside; filename and + function name are null-terminated strings allocated on compiletime. + The message, might be allocated on compiletime or during runtime. + + The proper way of accessing the status structure is yet to be + defined. Currently the structure is accessed directly, but it + has to be considered an implementation detail. There are also + macros to check for a set status. + When an Error is detected, also an ERROR is passed to the log. Because this isn't implemented yet, it is replaced by a call to printf. + + Unfortunately the compiler reports, that inside the macro + set_status, printf may be called with NULL [printf (NULL)], + although, this is explicitly debarred. + Some may argue, that in case of a fatal error, like if no memory can be allocated, a program should just give up and crash. However this behaviour is not very user-friendly. @@ -168,6 +207,36 @@ Validator: When a tag is made known to the Validator, which it already knows, the old id is returned and nothing is added. + The Validator saves the tags as an array. Now also another information + is added, which slots aren't used currently to spare expensive calls to + realloc. This led to a mere reimplementation of the functions. Tags + can't be deleted by now, but the adding function supports reusing empty + slots. Also the reading functions have to determine, whether a slot can + be read or is empty. + The tests were adjusted, but are buggy, so they should be rewritten in + the future. + + A registered tag can be deregistered by calling SH_Validator_deregister. + The data is removed, but the space is not deallocated, if it is not at + the end. This prevents copying data on removal and saves expensive calls + to realloc. Instead the empty space is added to the list of free blocks, + which allows to refill these spaces, if a new tag is being registered. + The space is finally deallocated, if the validator is being deallocated + or the tag written in the last block is removed. In this case, heavy + iteration is performed, as the list of free blocks is not ordered. The + next last tag at that time is determined by iterating over the list of + free blocks until some it is not found. + Note that even if there can be a lot of gaps in between, the Validator + will not allocate more space until all these gaps are refilled when a + new tag is registered, thus new space is only being allocated, if there + is really not enough space left. + Due to the 4 nested loops, there was an issue related to the + 72(80)-column rule. It can't be abided without severely impacting the + readability of the code. + + Copying a Validator could be useful if multiple html versions are to be + supported. Another use case is a blacklist XSS-Scanner. + Text: This is a data type to deal with frequently appending to a string. diff --git a/sefht.geany b/sefht.geany index 5dccf37..d417693 100644 --- a/sefht.geany +++ b/sefht.geany @@ -34,7 +34,7 @@ FILE_NAME_1=134;None;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2F FILE_NAME_2=1737;Sh;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fconfigure.ac;0;8 FILE_NAME_3=73;Make;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2FMakefile.am;0;8 FILE_NAME_4=19;C;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2Fmain.c;0;8 -FILE_NAME_5=1831;None;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fdocs%2Fcommit_messages.txt;0;8 +FILE_NAME_5=10380;None;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fdocs%2Fcommit_messages.txt;0;8 FILE_NAME_6=1867;Make;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2Flib%2FMakefile.am;0;8 FILE_NAME_7=18;C;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2Flib%2Fsefht%2Fcms.c;0;8 FILE_NAME_8=18;C;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2Flib%2Fsefht%2Fcms.h;0;8 -- GitLab