array_allocate(3)

1array_allocate(3)          Library Functions Manual          array_allocate(3)
2
3
4

NAME

6       array_allocate - make sure array has at least n elements allocated
7

SYNTAX

9       #include <array.h>
10
11       void* array_allocate(array* x, uint64 membersize, int64 pos);
12
13         array x;
14         int64 pos;
15         t* p = array_allocate(&x,sizeof(t),pos);
16
17

DESCRIPTION

19       array_allocate  makes  sure that enough bytes are allocated in x for at
20       least pos+1 objects of type t. (The size of t must be positive;  other‐
21       wise  the effects are undefined.) If not enough bytes are allocated (or
22       x is unallocated), array_allocate  allocates  more  bytes,  moving  the
23       dynamically  allocated region if necessary.  array_allocate often allo‐
24       cates somewhat more bytes than necessary, to save time later.
25
26       array_allocate then makes sure that the  number  of  bytes  initialized
27       covers  at  least those pos+1 objects. If not enough bytes are initial‐
28       ized, array_allocate initializes more bytes (setting them to 0), up  to
29       exactly the end of the pos+1st object.
30
31       array_allocate  then  returns  a  pointer  to the pos+1st object; i.e.,
32       object number pos, with objects numbered starting at  0.  This  pointer
33       can  be  used to change or inspect the object. The pointer can continue
34       to  be  used  through  subsequent  calls  to  array_get,   array_start,
35       array_length,  and array_bytes, but it must not be used after any other
36       operations on this array.
37
38       If something goes wrong, array_allocate returns 0, setting errno appro‐
39       priately,  without  touching x. In particular, array_allocate returns 0
40       if
41
42
43
44       ·      x has failed, or
45
46       ·      pos is negative, or
47
48       ·      not enough memory is available.
49
50       array_allocate does not change x to have failed;  if  you  want  to  do
51       that, use array_fail.
52
53

PERFORMANCE

55       This  function  can  call  realloc when the array needs to be enlarged.
56       Under exceptional circumstances, this can lead to blocking the  current
57       thread.   It  will also zero-fill the newly enlarged part of the array,
58       leading to all pages being mapped in by the  operating  system.   If  a
59       small  array  is enlarged to a very large array, this can lead to swap‐
60       ping and blocking.
61

NAME

SYNTAX

DESCRIPTION

PERFORMANCE

SEE ALSO