From d616e7db3a2325646e8647cdc433b12e9438c251 Mon Sep 17 00:00:00 2001 From: Tyge Løvset Date: Wed, 12 Jan 2022 10:55:35 +0100 Subject: Docs update, mmap.c example update. --- docs/ccommon_api.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/ccommon_api.md b/docs/ccommon_api.md index 46e25737..db9ef911 100644 --- a/docs/ccommon_api.md +++ b/docs/ccommon_api.md @@ -1,10 +1,11 @@ -# STC [ccommon](../include/stc/ccommon.h): Common definitions and handy macros +# STC [ccommon](../include/stc/ccommon.h): RAII and iterator macros -The following handy macros are safe to use, i.e. have no side-effects. +The following macros are recommended to use, and they safe/have no side-effects. ### c_auto, c_autovar, c_autoscope, c_autodefer -General ***defer*** mechanics for resource acquisition. These macros allows to specify the release of the -resource where the resource acquisition takes place. Makes it easier to verify that resources are released. +General ***defer*** mechanics for resource acquisition. These macros allows you to specify the +freeing of the resources at the point where the acquisition takes place. +The **checkauto** utility described below, ensures that the `c_auto*` macros are used correctly. | Usage | Description | |:---------------------------------------|:-----------------------------------------------------| @@ -17,13 +18,14 @@ resource where the resource acquisition takes place. Makes it easier to verify t For multiple variables, use either multiple **c_autovar** in sequence, or declare variable outside scope and use **c_autoscope**. Also, **c_auto** support up to 4 variables. ```c -c_autovar (uint8_t* buf = c_alloc_n(uint8_t, N), c_free(buf)) +c_autovar (uint8_t* buf = malloc(BUF_SIZE), free(buf)) c_autovar (FILE* f = fopen(fname, "rb"), fclose(f)) { int n = 0; - if (f && buf) - n = fread(buf, 1, N, f); - if (n > 0) doSomething(buf, n); + if (f && buf) { + n = fread(buf, 1, BUF_SIZE, f); + doSomething(buf, n); + } } c_autovar (cstr s = cstr_new("Hello"), cstr_drop(&s)) @@ -69,9 +71,9 @@ cvec_str readFile(const char* name) cvec_str vec = cvec_str_init(); // returned c_autovar (FILE* fp = fopen(name, "r"), fclose(fp)) - c_autovar (cstr line = cstr_null, cstr_drop(&line)) - while (cstr_getline(&line, fp)) - cvec_str_emplace_back(&vec, line.str); + c_autovar (cstr line = cstr_null, cstr_drop(&line)) + while (cstr_getline(&line, fp)) + cvec_str_emplace_back(&vec, line.str); return vec; } @@ -86,7 +88,7 @@ int main() The **checkauto** program will check the source code for any misuses of the `c_auto*` macros which may lead to resource leakages. The `c_auto*`- macros are implemented as one-time executed **for-loops**, so any `return` or `break` appearing within such a block will lead to resource leaks, as it will disable -the cleanup/drop method to be called. However, a `break` may (originally) been intended to break an immediate +the cleanup/drop method to be called. However, a `break` may (originally) been intended to break the immediate loop/switch outside the `c_auto` scope, so it would not work as intended in any case. The **checkauto** tool will report any such misusages. In general, one should therefore first break out of any inner loops with `break`, then use `c_breakauto` to break out of the `c_auto` scope(s). After this `return` may be used. @@ -94,19 +96,19 @@ with `break`, then use `c_breakauto` to break out of the `c_auto` scope(s). Afte Note that this is not a particular issue with the `c_auto*`-macros, as one must always make sure to unwind temporary allocated resources before a `return` in C. However, by using `c_auto*`-macros, - it is much easier to automatically detect misplaced return/break between resource acquisition and destruction. -- it prevent forgetting to call the destructor at the end. +- it prevents forgetting to call the destructor at the end. ```c for (int i = 0; i