author | Olivier Brunel
<jjk@jjacky.com> 2023-05-29 17:35:12 UTC |
committer | Olivier Brunel
<jjk@jjacky.com> 2023-07-05 07:39:26 UTC |
parent | 2c5b228717af968027680bbc73e5bfbb9d7f7754 |
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 */