netwib doc_html (version 5.39.0)

## main index

## section index

    /*-------------------------------------------------------------*/
    /***************************************************************
     * A netwib_array permits to store a dynamic number of items.  *
     * Those items all have the same size.                         *
     *                                                             *
     * The common implementation of such storage is :              *
     *   p = malloc(numitems*sizeof(item));                        *
     *   p[1] = ...;                                               *
     * However, if sizeof(item) is not a multiple of the processor *
     * size, a bus error occurs on strict processors (Alpha,       *
     * Sparc). For example, storing 5 items of size 3 can be       *
     * represented in memory (start at address 0x76543210) :       *
     *   .- address 0x76543210                                     *
     *   ABCABCABCABCABC                                           *
     * The second item is at address 0x76543213 (0x76543210+3)     *
     * which is invalid and causes a bus error.                    *
     * The second drawback of this common implementation is memory *
     * management is not efficient, because when p contains a lot  *
     * of items, this big buffer has to be reallocated.            *
     *                                                             *
     * Netwib's implementation is different. Instead of creating   *
     * an array of items, netwib creates an array of pointers to   *
     * items. This solves both above problems.                     *
     *                                                             *
     * Usage example:                                              *
     *   netwib_array a;                                           *
     *   struct foobar *pfb;                                       *
     *   netwib_er(netwib_array_init(sizeof(struct foobar),3,&a)); *
     *   pfb = (struct foobar *)a.p[0];                            *
     *   pfb->...;                                                 *
     *   for (i = 0; i < a.size; i++) {                            *
     *     pfb = (struct foobar *)a.p[i];                          *
     *     pfb->...;                                               *
     *   }                                                         *
     *   netwib_er(netwib_array_ctl_set_size(&a, 6));              *
     *   pfb = (struct foobar *)a.p[5];                            *
     *   netwib_er(netwib_array_close(&a));                        *
     ***************************************************************/

    /*-------------------------------------------------------------*/
    typedef struct {
      netwib_ptr *p;      /* array of pointers to items */
      netwib_uint32 size; /* size of p array (0 -> size-1) */
      netwib_ptr opaque;  /* internal storage is here. Do not use. */
    } netwib_array;
    typedef const netwib_array netwib_constarray;

    /*-------------------------------------------------------------*/
    /* Name : netwib_array_init
       Description :
         Initialize a netwib_array.
       Input parameter(s) :
         itemsize : size of items to store
         initialsize : initial number of items to store
       Input/output parameter(s) :
       Output parameter(s) :
         *parray : netwib_array initialized
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_array_init(netwib_uint32 itemsize,
                                 netwib_uint32 initialsize,
                                 netwib_array *parray);

    /*-------------------------------------------------------------*/
    /* Name : netwib_array_close
       Description :
         Close a netwib_array.
       Input parameter(s) :
       Input/output parameter(s) :
       Output parameter(s) :
         *parray : netwib_array to close
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_array_close(netwib_array *parray);

    /*-------------------------------------------------------------*/
    /* Types to control a netwib_array */
    typedef enum {
      NETWIB_ARRAY_CTLTYPE_SIZE = 1   /* request an array to grow
                                         or shrink */
    } netwib_array_ctltype;
    netwib_err netwib_array_ctl_set(netwib_array *parray,
                                    netwib_array_ctltype type,
                                    netwib_ptr p,
                                    netwib_uint32 ui);
    netwib_err netwib_array_ctl_get(netwib_array *parray,
                                    netwib_array_ctltype type,
                                    netwib_ptr p,
                                    netwib_uint32 *pui);

    /*-------------------------------------------------------------*/
    /* netwib_err f(netwib_array *parray, netwib_uint32 newsize); */
    #define netwib_array_ctl_set_size(parray,newsize) netwib_array_ctl_set(parray,NETWIB_ARRAY_CTLTYPE_SIZE,NULL,newsize)
    #define netwib_array_ctl_get_size(parray,pnewsize) netwib_array_ctl_get(parray,NETWIB_ARRAY_CTLTYPE_SIZE,NULL,pnewsize)

## main index

## section index