bionic (3) array_allocate.3.gz

NAME

       array_allocate - make sure array has at least n elements allocated

SYNTAX

       #include <array.h>

       void* array_allocate(array* x, uint64 membersize, int64 pos);

         array x;
         int64 pos;
         t* p = array_allocate(&x,sizeof(t),pos);

DESCRIPTION

       array_allocate makes sure that enough bytes are allocated in x for at least pos+1 objects of type t. (The
       size of t must be positive; otherwise the effects are undefined.) If not enough bytes are allocated (or x
       is  unallocated),  array_allocate  allocates  more  bytes,  moving  the  dynamically  allocated region if
       necessary.  array_allocate often allocates somewhat more bytes than necessary, to save time later.

       array_allocate then makes sure that the number of bytes initialized covers at least those pos+1  objects.
       If  not  enough  bytes  are initialized, array_allocate initializes more bytes (setting them to 0), up to
       exactly the end of the pos+1st object.

       array_allocate then returns a pointer to the pos+1st  object;  i.e.,  object  number  pos,  with  objects
       numbered  starting  at  0.  This  pointer  can  be  used to change or inspect the object. The pointer can
       continue to be used through subsequent calls to array_get, array_start,  array_length,  and  array_bytes,
       but it must not be used after any other operations on this array.

       If  something  goes  wrong, array_allocate returns 0, setting errno appropriately, without touching x. In
       particular, array_allocate returns 0 if

       •      x has failed, or

       •      pos is negative, or

       •      not enough memory is available.

       array_allocate does not change x to have failed; if you want to do that, use array_fail.

PERFORMANCE

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

SEE ALSO

       array_get(3), array_start(3), array_fail(3)

                                                                                               array_allocate(3)