Welcome to little lamb

Code » limb » commit 8e4c7f5

Add genalloc.h & genalloc_remove()

author Olivier Brunel
2023-05-29 17:35:12 UTC
committer Olivier Brunel
2023-07-05 07:39:26 UTC
parent 2c5b228717af968027680bbc73e5bfbb9d7f7754

Add genalloc.h & genalloc_remove()

Also start handling such headers differently: since we intend to use
them as "replacement" for skalibs' we'll document everything we expect
to be used, somewhat as if "our own".

So here, we document all genalloc functions, not just our additions. In
general, we'll do that for all such headers, expect we might not always
document *everything* but what we intend to use.
That is to say, there might be stuff we don't care for, or haven't had
time to look into, that we'll just "ignore" for now.

src/doc/genalloc.h.0.md +106 -0
src/doc/genalloc.h/genalloc_append.3.md +1 -0
src/doc/genalloc.h/genalloc_cat.3.md +72 -0
src/doc/genalloc.h/genalloc_catb.3.md +1 -0
src/doc/genalloc.h/genalloc_copy.3.md +1 -0
src/doc/genalloc.h/genalloc_copyb.3.md +1 -0
src/doc/genalloc.h/genalloc_deepfree.3.md +1 -0
src/doc/genalloc.h/genalloc_deepfree_size.3.md +1 -0
src/doc/genalloc.h/genalloc_free.3.md +1 -0
src/doc/genalloc.h/genalloc_insert.3.md +1 -0
src/doc/genalloc.h/genalloc_insertb.3.md +1 -0
src/doc/genalloc.h/genalloc_len.3.md +1 -0
src/doc/genalloc.h/genalloc_ready.3.md +1 -0
src/doc/genalloc.h/genalloc_ready_tuned.3.md +78 -0
src/doc/genalloc.h/genalloc_readyplus.3.md +1 -0
src/doc/genalloc.h/genalloc_remove.3.md +36 -0
src/doc/genalloc.h/genalloc_reverse.3.md +19 -0
src/doc/genalloc.h/genalloc_s.3.md +40 -0
src/doc/genalloc.h/genalloc_setlen.3.md +1 -0
src/doc/genalloc.h/genalloc_shrink.3.md +1 -0
src/doc/include/skalibs.md +5 -0
src/liblimb/include/limb/genalloc.h +11 -0

diff --git a/src/doc/genalloc.h.0.md b/src/doc/genalloc.h.0.md
new file mode 100644
index 0000000..8b6b4a4
--- /dev/null
+++ b/src/doc/genalloc.h.0.md
@@ -0,0 +1,106 @@
+% limb manual
+% genalloc.h(0)
+
+# NAME
+
+genalloc.h - general heap memory management
+
+# SYNOPSIS
+
+    #include <limb/genalloc.h>
+
+# DESCRIPTION
+
+This header defines functions to work heap-allocated memory. It is implemented
+on top of *stralloc* (See [stralloc.h](0) for more) providing an API to store
+dynamic arrays of fixed-size objects.
+
+<inc skalibs.md>
+
+## Types
+
+The following types are defined :
+
+: *genalloc*
+:: A *struct stralloc*, as *genalloc* is implemented on top of *stralloc*
+
+## Objects
+
+The following objects are defined :
+
+: *genalloc_zero*
+:: An empty *genalloc*, which can be used for initialization.
+
+## Macros
+
+The following macros are defined :
+
+: *GENALLOC_ZERO*
+:: Value to initialize a stack-allocated *genalloc*.
+
+## Functions
+
+The following functions/macros are defined :
+
+: [genalloc_ready_tuned](3)
+:: Ensure there's enough space in a *genalloc*.
+
+: [genalloc_ready](3)
+:: Ensure there's enough space in a *genalloc*.
+
+: [genalloc_readyplus](3)
+:: Ensure there's enough extra space in a *genalloc*.
+
+
+: [genalloc_free](3)
+:: Free memory associated with a *genalloc*.
+
+: [genalloc_deepfree](3)
+:: Free memory associated with a *genalloc*.
+
+: [genalloc_deepfree_size](3)
+:: Free memory associated with a *genalloc*.
+
+: [genalloc_shrink](3)
+:: Reduce memory usage to what's used.
+
+
+: [genalloc_s](3)
+:: Return a pointer to the data in a *genalloc*
+
+: [genalloc_len](3)
+:: Return the length/number of element in a *genalloc*
+
+: [genalloc_setlen](3)
+:: Set the length/number of element in a *genalloc*
+
+
+: [genalloc_copyb](3)
+:: Copy data into a *genalloc*.
+
+: [genalloc_copy](3)
+:: Copy content of a *genalloc* into another one.
+
+: [genalloc_catb](3)
+:: Append data into a *genalloc*.
+
+: [genalloc_cat](3)
+:: Append the content of a *genalloc* into another one.
+
+: [genalloc_append](3)
+:: Append a character into a *genalloc*.
+
+
+: [genalloc_insertb](3)
+:: Insert data into a *genalloc* at a specific offset.
+
+: [genalloc_insert](3)
+:: Insert the content of a *genalloc* into another one at a specific offset.
+
+
+: [genalloc_remove](3)
+:: Remove data from a *genalloc*.
+
+
+: [genalloc_reverse](3)
+:: Reverse the content of a *genalloc*.
diff --git a/src/doc/genalloc.h/genalloc_append.3.md b/src/doc/genalloc.h/genalloc_append.3.md
new file mode 120000
index 0000000..fedaf9c
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_append.3.md
@@ -0,0 +1 @@
+genalloc_cat.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_cat.3.md b/src/doc/genalloc.h/genalloc_cat.3.md
new file mode 100644
index 0000000..ae36521
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_cat.3.md
@@ -0,0 +1,72 @@
+% limb manual
+% genalloc_cat(3)
+
+# NAME
+
+genalloc_catb, genalloc_cat, genalloc_copyb, genalloc_copy, genalloc_insertb,
+genalloc_insert, genalloc_append - adding data into a genalloc
+
+# SYNOPSIS
+
+    #include <limb/genalloc.h>
+
+```pre hl
+int genalloc_catb(<em>type</em>, genalloc *<em>ga</em>, const <em>type</em> *<em>el</em>, int <em>num</em>)
+int genalloc_cat(<em>type</em>, genalloc *<em>ga</em>, const genalloc *<em>gasce</em>)
+
+int genalloc_copyb(<em>type</em>, genalloc *<em>ga</em>, const <em>type</em> *<em>el</em>, int <em>num</em>)
+int genalloc_copy(<em>type</em>, genalloc *<em>ga</em>, const genalloc *<em>gasce</em>)
+
+int genalloc_insertb(<em>type</em>, genalloc *<em>ga</em>, size_t <em>offset</em>, const <em>type</em> *<em>el</em>, int <em>num</em>)
+int genalloc_insert(<em>type</em>, genalloc *<em>ga</em>, size_t <em>offset</em>, const genalloc *<em>gasce</em>)
+
+int genalloc_append(<em>type</em>, genalloc *<em>ga</em>, type *<em>el</em>)
+```
+
+# DESCRIPTION
+
+The `genalloc_catb`() macro appends the content of memory pointed by `el` -
+which must be `num` elements of type `type` - into the genalloc pointed by `ga`.
+
+The `genalloc_cat`() macro is similar to `genalloc_catb`() macro but
+appending the content of genalloc `gasce`.
+
+
+The `genalloc_copyb`() macro copies the content of memory pointed by `el` -
+which must be `num` elements of type `type` - into the genalloc pointed by `ga`.
+That is, the genalloc will only contain `el` afterwards.
+
+The `genalloc_copy`() macro is similar to `genalloc_copyb`() macro but
+copying the content of genalloc `gasce`.
+
+
+The `genalloc_insertb`() macro inserts the content of memory pointed by
+`el` - which must be `num` elements of type `type` -  into the genalloc pointed
+by `ga` at offset `offset`.
+
+The `genalloc_insert`() macro is similar to `genalloc_insertb`() macro but
+inserting the content of genalloc `gasce`.
+
+
+The `genalloc_append`() macro appends the element of type `type` pointed be
+`el` into the genalloc pointed by `ga`.
+
+! NOTE:
+! Obviously all these macros ensure that there is enough room available in the
+! genalloc `ga` before writing data into it.
+
+# RETURN VALUE
+
+These functions return 1 on success. Otherwise they return 0 and set `errno` to
+indicate the error.
+
+# ERRORS
+
+The `genalloc_catb`(), `genalloc_cat`(), `genalloc_copyb`(), `genalloc_copy`(),
+`genalloc_insertb`() and `genalloc_insert`() functions may fail for the errors
+described for [stralloc_catb](3), [stralloc_cat](3), [stralloc_copyb](3),
+[stralloc_copy](3), [stralloc_insertb](3) and [stralloc_insert](3) respectively.
+
+The `genalloc_append`() function may fail for the error described for
+[stralloc_catb](3).
+
diff --git a/src/doc/genalloc.h/genalloc_catb.3.md b/src/doc/genalloc.h/genalloc_catb.3.md
new file mode 120000
index 0000000..fedaf9c
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_catb.3.md
@@ -0,0 +1 @@
+genalloc_cat.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_copy.3.md b/src/doc/genalloc.h/genalloc_copy.3.md
new file mode 120000
index 0000000..fedaf9c
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_copy.3.md
@@ -0,0 +1 @@
+genalloc_cat.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_copyb.3.md b/src/doc/genalloc.h/genalloc_copyb.3.md
new file mode 120000
index 0000000..fedaf9c
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_copyb.3.md
@@ -0,0 +1 @@
+genalloc_cat.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_deepfree.3.md b/src/doc/genalloc.h/genalloc_deepfree.3.md
new file mode 120000
index 0000000..ef88e13
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_deepfree.3.md
@@ -0,0 +1 @@
+genalloc_ready_tuned.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_deepfree_size.3.md b/src/doc/genalloc.h/genalloc_deepfree_size.3.md
new file mode 120000
index 0000000..ef88e13
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_deepfree_size.3.md
@@ -0,0 +1 @@
+genalloc_ready_tuned.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_free.3.md b/src/doc/genalloc.h/genalloc_free.3.md
new file mode 120000
index 0000000..ef88e13
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_free.3.md
@@ -0,0 +1 @@
+genalloc_ready_tuned.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_insert.3.md b/src/doc/genalloc.h/genalloc_insert.3.md
new file mode 120000
index 0000000..fedaf9c
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_insert.3.md
@@ -0,0 +1 @@
+genalloc_cat.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_insertb.3.md b/src/doc/genalloc.h/genalloc_insertb.3.md
new file mode 120000
index 0000000..fedaf9c
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_insertb.3.md
@@ -0,0 +1 @@
+genalloc_cat.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_len.3.md b/src/doc/genalloc.h/genalloc_len.3.md
new file mode 120000
index 0000000..98f1774
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_len.3.md
@@ -0,0 +1 @@
+genalloc_s.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_ready.3.md b/src/doc/genalloc.h/genalloc_ready.3.md
new file mode 120000
index 0000000..ef88e13
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_ready.3.md
@@ -0,0 +1 @@
+genalloc_ready_tuned.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_ready_tuned.3.md b/src/doc/genalloc.h/genalloc_ready_tuned.3.md
new file mode 100644
index 0000000..d601405
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_ready_tuned.3.md
@@ -0,0 +1,78 @@
+% limb manual
+% genalloc_ready_tuned(3)
+
+# NAME
+
+genalloc_ready_tuned, genalloc_ready, genalloc_readyplus, genalloc_free,
+genalloc_deepfree, genalloc_deepfree_size, genalloc_shrink - allocate and
+free memory associated with a genalloc
+
+# SYNOPSIS
+
+    #include <limb/genalloc.h>
+
+```pre hl
+int genalloc_ready_tuned(<em>type</em>, genalloc *<em>ga</em>, int <em>num</em>, size_t <em>base</em>, size_t <em>a</em>, size_t <em>b</em>)
+int genalloc_ready(<em>type</em>, genalloc *<em>ga</em>, int <em>num</em>)
+int genalloc_readyplus(<em>type</em>, genalloc *<em>ga</em>, int <em>num</em>)
+
+int genalloc_shrink(<em>type</em>, genalloc *<em>ga</em>)
+
+void genalloc_free(<em>type</em>, genalloc *<em>ga</em>)
+void genalloc_deepfree(<em>type</em>, genalloc *<em>ga</em>, free_func *<em>fn</em>)
+void genalloc_deepfree_size(genalloc *<em>ga</em>, free_func *<em>fn</em>, size_t <em>len</em>)
+```
+
+# DESCRIPTION
+
+The `genalloc_ready`() macro ensure that genalloc pointed by `ga` has enough
+memory for `num` elements of type `type`, reallocating memory if needed.
+This does not mean as much is available, as there might be data in use already.
+
+The `genalloc_readyplus`() macro ensure that genalloc pointed by `ga` has enough
+memory available for `num` more elements of type `type`, reallocating memory if
+needed. Available here means space that is allocated but not yet in use, making
+this the most commonly used way to prepare a *genalloc* before writing data into
+it.
+
+The `genalloc_ready_tuned`() is similar to `genalloc_ready`() but with more
+fine-tuning settings.
+
+Note that this is only needed when writing into the *genalloc* directly, as all
+functions of the *genalloc* API (e.g. [genalloc_append](3)) handles that
+automatically.
+
+The `genalloc_shrink`() macro will ensure that the allocated memory is only
+as large as is in use in genalloc `ga`.
+
+The `genalloc_deepfree_size`() function is useful when storing pointers in a
+genalloc, or any data that must have associated memory freed for each elements.
+It will iterate over the data in genalloc `ga` - which must contain elements of
+`len` bytes - and call the function `fn` with the address of each element as
+argument.
+Once done, it will free all memory associated with the genalloc `ga` itself.
+
+The `genalloc_deepfree`() macro is similar to `genalloc_deepfree_size`() but for
+genalloc containing elements of type `type`.
+
+The `genalloc_free`() macro will free all memory associated with the genalloc
+`ga`.
+
+# RETURN VALUE
+
+These functions (except for `genalloc_free`(), `genalloc_deepfree`() and
+`genalloc_deepfree_size`()) return 1 on success. Otherwise they return 0 and
+set `errno` to indicate the error.
+
+# ERRORS
+
+The `genalloc_ready_tuned`(), `genalloc_ready`() and `genalloc_readyplus`()
+functions may fail for the errors described for [stralloc_ready_tuned](3),
+[stralloc_ready](3) and [stralloc_readuplus](3), respectively.
+
+The `genalloc_shrink`() function may fail for the errors described for
+[stralloc_shrink](3).
+
+# SEE ALSO
+
+[genalloc_remove](3)
diff --git a/src/doc/genalloc.h/genalloc_readyplus.3.md b/src/doc/genalloc.h/genalloc_readyplus.3.md
new file mode 120000
index 0000000..ef88e13
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_readyplus.3.md
@@ -0,0 +1 @@
+genalloc_ready_tuned.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_remove.3.md b/src/doc/genalloc.h/genalloc_remove.3.md
new file mode 100644
index 0000000..c6b143a
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_remove.3.md
@@ -0,0 +1,36 @@
+% limb manual
+% genalloc_remove(3)
+
+# NAME
+
+genalloc_remove - remove data from a genalloc
+
+# SYNOPSIS
+
+    #include <limb/genalloc.h>
+
+```pre hl
+int genalloc_remove(<em>type</em>, genalloc *<em>ga</em>, int <em>offset</em>, int <em>num</em>)
+```
+
+# DESCRIPTION
+
+The `genalloc_remove`() macro removes `num` elements from the genalloc `ga`
+starting with element `offset`th.
+
+The member `len` will be adjusted and data afterwards moved as needed, but no
+re-allocation occurs.
+
+# RETURN VALUE
+
+The `genalloc_remove`() function returns 1 on success. Otherwise it returns 0
+and sets `errno` to indicate the error.
+
+# ERRORS
+
+The `genalloc_remove`() function may fail for the errors described for
+[stralloc_remove](3).
+
+# SEE ALSO
+
+[genalloc_shrunk](3)
diff --git a/src/doc/genalloc.h/genalloc_reverse.3.md b/src/doc/genalloc.h/genalloc_reverse.3.md
new file mode 100644
index 0000000..d9b3c1e
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_reverse.3.md
@@ -0,0 +1,19 @@
+% limb manual
+% genalloc_reverse(3)
+
+# NAME
+
+genalloc_reverse - reverse the content of a genalloc
+
+# SYNOPSIS
+
+    #include <limb/genalloc.h>
+
+```pre hl
+void genalloc_reverse(<em>type</em>, genalloc *<em>ga</em>)
+```
+
+# DESCRIPTION
+
+The `genalloc_reverse`() macro reverses the order of elements in genalloc `ga`,
+which must contain elements of type `type`.
diff --git a/src/doc/genalloc.h/genalloc_s.3.md b/src/doc/genalloc.h/genalloc_s.3.md
new file mode 100644
index 0000000..116b79c
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_s.3.md
@@ -0,0 +1,40 @@
+% limb manual
+% genalloc_s(3)
+
+# NAME
+
+genalloc_s, genalloc_len, genalloc_setlen - accessing genalloc data
+
+# SYNOPSIS
+
+    #include <limb/genalloc.h>
+
+```pre hl
+<em>type</em> *genalloc_s(<em>type</em>, genalloc *<em>ga</em>)
+size_t genalloc_len(<em>type</em>, genalloc *<em>ga</em>)
+void genalloc_setlen(<em>type</em>, genalloc *<em>ga</em>, int <em>num</em>)
+```
+
+# DESCRIPTION
+
+The `genalloc_s`() macro returns a pointer to the data contained in genalloc
+`ga`, which must be elements of type `type`. This macro is intended as a way to
+access data stored inside a genalloc, allowing to read or write said data.
+A typical way to access a specific element might be :
+    mytype *el = &genalloc_s(mytype, ga)[idx];
+
+The `genalloc_len`() macro returns the number of elements contained in genalloc
+`ga`, assuming it contains elements of of type `type`.
+
+The `genalloc_setlen`() macro sets the used size of genalloc `ga` to be that of
+`num` elements of type `type`. Note that no checks are performed, it is up to
+the caller of ensure the size set is valid. Much like when setting member `len`
+of an *stralloc*.
+
+# RETURN VALUE
+
+The `genalloc_s`() macro returns a pointer to the data in genalloc `ga`,
+type-casted to `type`.
+
+The `genalloc_len`() macro returns the number of elements of type `type` in
+genalloc `ga`.
diff --git a/src/doc/genalloc.h/genalloc_setlen.3.md b/src/doc/genalloc.h/genalloc_setlen.3.md
new file mode 120000
index 0000000..98f1774
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_setlen.3.md
@@ -0,0 +1 @@
+genalloc_s.3.md
\ No newline at end of file
diff --git a/src/doc/genalloc.h/genalloc_shrink.3.md b/src/doc/genalloc.h/genalloc_shrink.3.md
new file mode 120000
index 0000000..ef88e13
--- /dev/null
+++ b/src/doc/genalloc.h/genalloc_shrink.3.md
@@ -0,0 +1 @@
+genalloc_ready_tuned.3.md
\ No newline at end of file
diff --git a/src/doc/include/skalibs.md b/src/doc/include/skalibs.md
new file mode 100644
index 0000000..10b2c05
--- /dev/null
+++ b/src/doc/include/skalibs.md
@@ -0,0 +1,5 @@
+! INFO: skalibs
+! This header is a complement to skalibs' own header, intended to be used as a
+! "replacement". However, instead of re-inventing the wheel, it depends/includes
+! skalibs' header, and some of the functions below are actually implemented in
+! skalibs, or macros to such functions.
diff --git a/src/liblimb/include/limb/genalloc.h b/src/liblimb/include/limb/genalloc.h
new file mode 100644
index 0000000..517a1fe
--- /dev/null
+++ b/src/liblimb/include/limb/genalloc.h
@@ -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 */
+#ifndef LIMB_GENALLOC_H
+#define LIMB_GENALLOC_H
+
+#include <skalibs/genalloc.h>
+
+#define genalloc_remove(type, ga, offset, n)   stralloc_remove((ga), (offset) * sizeof(type), (n) * sizeof(type))
+
+#endif /* LIMB_GENALLOC_H */