Welcome to little lamb

Code » limb » commit f5be997

cdbmake.h: Add CDBMAKER_SA_ZERO & cdbmaker_sa_init()..

author Olivier Brunel
2023-04-18 20:18:50 UTC
committer Olivier Brunel
2023-05-20 18:06:37 UTC
parent 5716d1983de2b48421e50468541c1e534e79d536

cdbmake.h: Add CDBMAKER_SA_ZERO & cdbmaker_sa_init()..

..and allows to re-use the same maker after a successful
cdbmaker_sa_finish(), to create another cdb.

src/doc/cdbmake.h.0.md +11 -1
src/doc/cdbmake.h/cdbmaker_sa_start.3.md +26 -8
src/liblimb/cdbmake.h/cdbmaker_sa_init.c +11 -0
src/liblimb/cdbmake.h/cdbmaker_sa_start.c +1 -2
src/liblimb/include/limb/cdbmake.h +5 -2

diff --git a/src/doc/cdbmake.h.0.md b/src/doc/cdbmake.h.0.md
index 271e455..b630e24 100644
--- a/src/doc/cdbmake.h.0.md
+++ b/src/doc/cdbmake.h.0.md
@@ -28,12 +28,19 @@ The following structures are defined :
 : *struct cdbmaker_sa*
 :: Semi-opaque structure used during the creating of a cdb in-memory.
 
+## Macros
+
+The following macros are defined :
+
+: *CDBMAKER_SA_ZERO*
+:: Can be used to initialized a *cdbmaker_sa* structure.
+
 ## Types
 
 The followng types are defined :
 
 : *cdbmaker_sa*
-:: Semi-opaque structure used durng the creating of a cdb in-memory.
+:: Semi-opaque structure used during the creating of a cdb in-memory.
 
 ## Functions
 
@@ -48,5 +55,8 @@ The following functions are defined :
 : [cdbmaker_sa_free](3)
 :: To free memory associated with a semi-opaque *cdbmaker_sa* when done.
 
+: [cdbmaker_sa_init](3)
+:: To initialize a *cdbmaker_sa* if not initalized through *CDBMAKER_SA_ZERO*.
+
 : [cdbmaker_sa_start](3)
 :: Similar to [cdbmake_start](3) but the cdb will be created in-memory.
diff --git a/src/doc/cdbmake.h/cdbmaker_sa_start.3.md b/src/doc/cdbmake.h/cdbmaker_sa_start.3.md
index e232bb9..d9a7077 100644
--- a/src/doc/cdbmake.h/cdbmaker_sa_start.3.md
+++ b/src/doc/cdbmake.h/cdbmaker_sa_start.3.md
@@ -3,7 +3,7 @@
 
 # NAME
 
-cdbmaker\_sa\_start, cdbmaker\_sa\_add, cdbmaker\_sa\_finish,
+cdbmaker\_sa\_init, cdbmaker\_sa\_start, cdbmaker\_sa\_add, cdbmaker\_sa\_finish,
 cdbmaker\_sa\_free - create a cdb in memory
 
 # SYNOPSIS
@@ -11,21 +11,33 @@ cdbmaker\_sa\_free - create a cdb in memory
     #include <limb/cdbmake.h>
 
 ```pre hl
-int cdbmaker_sa_finish(cdbmaker_sa *<em>mkr</em>)
-int cdbmaker_sa_add(cdbmaker_sa *<em>mkr</em>, const char *<em>key</em>, u32 <em>klen</em>, const char *<em>data</em>, u32 <em>dlen</em>)
+#define CDBMAKER_SA_ZERO
+
+void cdbmaker_sa_init(cdbmaker_sa *<em>mkr</em>)
 int cdbmaker_sa_start(cdbmaker_sa *<em>mkr</em>)
+int cdbmaker_sa_add(cdbmaker_sa *<em>mkr</em>, const char *<em>key</em>, u32 <em>klen</em>, const char *<em>data</em>, u32 <em>dlen</em>)
+int cdbmaker_sa_finish(cdbmaker_sa *<em>mkr</em>)
 void cdbmaker_sa_free(cdbmaker_sa *<em>mkr</em>)
 ```
 
 # DESCRIPTION
 
+Before using a *cdbmaker_sa* it should first be properly initialized. This can
+be done upon declaration using the *CDBMAKER_SA_ZERO* macro. If not, the
+`cdbmaker_sa_init`() function should then be called first.
+
 The `cdbmaker_sa_start`(), `cdbmaker_sa_add`() and `cdbmaker_sa_finish`()
 functions are similar to [cdbmake_start](3), [cdbmake_add](3) and
 [cdbmake_finish](3) respectively, only the resulting cdb will not be written to
 a file but instead be available in memory.
 
-The `cdbmaker_sa_start`() initializes the semi-opaque structure pointed to by
-`mkr` in order to begin creation of a cdb.
+The `cdbmaker_sa_start`() prepares the semi-opaque structure pointed to by
+`mkr` in order to begin creation of a new cdb. Said structure must have
+previously been initialized as mentioned before.
+
+Note that, after a successful call to `cdbmaker_sa_finish`() it is possible to
+re-use the same *cdbmaker_sa* structure, to create another cdb, by calling
+`cdbmaker_sa_start`() again.
 
 The `cdbmaker_sa_add`() function is to be called for each element to be added to
 the cdb, specifying the key pointed to by `key` of length `klen` bytes, and the
@@ -44,9 +56,10 @@ which is a *stralloc*, which - after a successful call to
 `cdbmaker_sa_finish`() - will hold the newly-created cdb (i.e. the content of a
 cdb file), available from `mkr->sa.s` for a length of `mkr->sa.len` bytes.
 
-When done with the cdb, the `cdbmaker_sa_free`() function must be called in
-order to free memory associated with the semi-opaque structure pointed to by
-`mkr`.
+The `cdbmaker_sa_free`() function will free memory associated with the semi-opaque
+structure pointed to by `mkr`, starting with the generated cdb data. It is not
+needed to use it before calling `cdbmaker_sa_start`() again in order to generate
+a new cdb, thusly re-using the already allocated memory area.
 
 # RETURN VALUE
 
@@ -62,6 +75,11 @@ fail if :
 : *ENOMEM*
 :: Not enough memory to create to cdb.
 
+The `cdbmaker_sa_start`() function may also fail if :
+
+: *EINVAL*
+:: The *cdbmaker_sa* structure is not in a valid/properly initialized state.
+
 The `cdbmaker_sa_add`() function may also fail if :
 
 : *EOVERFLOW*
diff --git a/src/liblimb/cdbmake.h/cdbmaker_sa_init.c b/src/liblimb/cdbmake.h/cdbmaker_sa_init.c
new file mode 100644
index 0000000..94003e2
--- /dev/null
+++ b/src/liblimb/cdbmake.h/cdbmaker_sa_init.c
@@ -0,0 +1,11 @@
+/* This file is part of limb                           https://lila.oss/limb
+ * Copyright (C) 2023 Olivier Brunel                          jjk@jjacky.com */
+/* SPDX-License-Identifier: GPL-2.0-only */
+#include <limb/cdbmake.h>
+
+void
+cdbmaker_sa_init(cdbmaker_sa *m)
+{
+    m->sa = stralloc_zero;
+    m->hplist = genalloc_zero;
+}
diff --git a/src/liblimb/cdbmake.h/cdbmaker_sa_start.c b/src/liblimb/cdbmake.h/cdbmaker_sa_start.c
index 15e36fb..0c567bb 100644
--- a/src/liblimb/cdbmake.h/cdbmaker_sa_start.c
+++ b/src/liblimb/cdbmake.h/cdbmaker_sa_start.c
@@ -6,8 +6,7 @@
 int
 cdbmaker_sa_start(cdbmaker_sa *m)
 {
-    m->sa = stralloc_zero;
-    m->hplist = genalloc_zero;
+    m->sa.len = m->hplist.len = 0;
     if (!stralloc_readyplus(&m->sa, 2048))
         return 0;
     m->sa.len = 2048;
diff --git a/src/liblimb/include/limb/cdbmake.h b/src/liblimb/include/limb/cdbmake.h
index 2447cb8..f83c6b4 100644
--- a/src/liblimb/include/limb/cdbmake.h
+++ b/src/liblimb/include/limb/cdbmake.h
@@ -16,9 +16,12 @@ struct cdbmaker_sa
 };
 typedef struct cdbmaker_sa cdbmaker_sa;
 
-extern int cdbmaker_sa_finish(cdbmaker_sa *m);
-extern int cdbmaker_sa_add(cdbmaker_sa *m, const char *key, u32 klen, const char *data, u32 dlen);
+#define CDBMAKER_SA_ZERO        { STRALLOC_ZERO, GENALLOC_ZERO }
+
+extern void cdbmaker_sa_init(cdbmaker_sa *m);
 extern int cdbmaker_sa_start(cdbmaker_sa *m);
+extern int cdbmaker_sa_add(cdbmaker_sa *m, const char *key, u32 klen, const char *data, u32 dlen);
+extern int cdbmaker_sa_finish(cdbmaker_sa *m);
 extern void cdbmaker_sa_free(cdbmaker_sa *m);
 
 #endif /* LIMB_CDBMAKE_H */