dynarray: Make the module usable on its own

[Bruno Haible]

Paul Eggert wrote:
> Perhaps it'd work without the "#define __libc_dynarray_resize 
> gl_dynarray_resize" etc. lines, because the two sets of 
> __libc_*dynarray* functions would be in different C namespaces? But it 
> might be confusing to debug.

No, there would be conflicts with glibc. In C, the namespace scope is
the compilation unit. Since each of the files malloc/dynarray_*.c is a
separate compilation unit, we would be colliding with the __libc_*
symbols defined by glibc (both with dynamic and with static linking).

Since dynarray looks useful, I wrote a small unit test, to see how the
module can be used on its own. I noticed three things:

I) A compilation error because "intprops.h" is included by not present.

II) It's not immediately clear which files to include. I define

#define DYNARRAY_STRUCT int_sequence
#define DYNARRAY_ELEMENT int
#define DYNARRAY_PREFIX intseq_

and then:

* With just <dynarray.h>:

In file included from ../../gltests/../gllib/dynarray.h:29:0,
                 from ../../gltests/test-dynarray.c:25:
../../gltests/../gllib/malloc/dynarray.h:171:1: warning: return type defaults 
to 'int' [-Wimplicit-int]
 libc_hidden_proto (__libc_dynarray_emplace_enlarge)
 ^
../../gltests/../gllib/malloc/dynarray.h: In function 'libc_hidden_proto':
../../gltests/../gllib/malloc/dynarray.h:172:1: error: expected declaration 
specifiers before 'libc_hidden_proto'
 libc_hidden_proto (__libc_dynarray_resize)
 ^


* With <libc-config.h> and <dynarray.h>:

../../gltests/test-dynarray.c: In function 'main':
../../gltests/test-dynarray.c:41:23: error: storage size of 's' isn't known
   struct int_sequence s;
                       ^


* With just <malloc/dynarray-skeleton.c>:

In file included from ../../gltests/../gllib/malloc/dynarray-skeleton.c:88:0,
                 from ../../gltests/test-dynarray.c:26:
../../gltests/../gllib/malloc/dynarray.h:171:1: warning: return type defaults 
to 'int' [-Wimplicit-int]
 libc_hidden_proto (__libc_dynarray_emplace_enlarge)
 ^
../../gltests/../gllib/malloc/dynarray.h: In function 'libc_hidden_proto':
../../gltests/../gllib/malloc/dynarray.h:172:1: error: expected declaration 
specifiers before 'libc_hidden_proto'
 libc_hidden_proto (__libc_dynarray_resize)
 ^


* With <libc-config.h> and <malloc/dynarray-skeleton.c>:

test-dynarray.o: In function `intseq_add__':
/media/develdata/devel/GNULIB/testdir4/build-64/gltests/../../gltests/../gllib/malloc/dynarray-skeleton.c:281:
 undefined reference to `__libc_dynarray_emplace_enlarge'
test-dynarray.o: In function `intseq_at':
/media/develdata/devel/GNULIB/testdir4/build-64/gltests/../../gltests/../gllib/malloc/dynarray-skeleton.c:253:
 undefined reference to `__libc_dynarray_at_failure'
collect2: error: ld returned 1 exit status


* So the result is that all of these files need to be included:

#include <libc-config.h>
#include <dynarray.h>
#include <malloc/dynarray-skeleton.c>

But that is not a proper interface for a module. To use a module, one should
need to include one file, not three.


III) The API documentation needs to be gathered from three places:
malloc/dynarray.h has tutorial documentation that is not consumable without
having read the reference documentation. The reference documentation is
in malloc/dynarray-skeleton.c, at the top of the file and then mixed with
the implementation. *shudder*


The following two patches bring this in order, and add a unit test.


2021-03-06  Bruno Haible  <bruno@clisp.org>

        dynarray: Add tests.
        * tests/test-dynarray.c: New file.
        * modules/dynarray-tests: New file.

        dynarray: Make the module usable on its own.
        * lib/dynarray.h: Document the exported API. Comments taken from
        lib/malloc/dynarray-skeleton.c and lib/malloc/dynarray.h.
        Distinguish an internal include from an include for instantiation.
        In the latter case, include <libc-config.h> and
        <malloc/dynarray-skeleton.c>.
        * modules/dynarray (Depends-on): Add intprops.
        (Include): Reduce to just "dynarray.h".

0001-dynarray-Make-the-module-usable-on-its-own.patch
Description: Text Data

0002-dynarray-Add-tests.patch
Description: Text Data