TABLE OF CONTENTS

trish2/bunch [ Modules ]

[ Top ] [ Modules ]

NAME

bunch

SYNOPSIS

 #include <bunch.h>

DESCRIPTION

The bunch module allows to allocate several pointers of the same size at once. The provided bunch_* functions guarantee that the object won't move. The advantages are:

A bunch allocates objects in blocks of a given size, then you "claim" pointers from the allocated blocks. The bunch keeps an array of blocks with the number of remaining unclaimed objects. When you claim a pointer to N objects, it will look for a block that has enough remaining objects and returns a pointer to an array of N objects. This has three consequences:

Thus it will leave you the delicate exercise to estimate a good block size: large enough to allow larger arrays, but not too large there's not too much waisted memory. There are two mechanisms to contain the consequences of waisted allocation. The bunch_print_info function will give a summary of allocated objects, claimed objects and so on. Also the bunch_save function, used to dump the bunch into a file, may prune unclaimed objects. However if you load a pruned bunch, you cannot claim pointers anymore.

EXAMPLE

The following code creates a bunch of char and copies in the command line arguments. 

     int main(int argc, char **argv) {
       bunch_t *bunch = bunch_new(sizeof(char), 1000);
       char **s = calloc(argc, sizeof(char *));
       int i;


       for(i = 0; i < argc; i++) {
         s[i] = bunch_claim(bunch, strlen(argv[1]) + 1);
         strcat(s[i], argv[i]);
       }


       ... do something with s ...


       bunch_free(bunch);
       free(s);
       return 1;
     }

The second example shows how write a bunch into a file.

SEE ALSO

bunch_t, bunch_block_t, BUNCH_PRUNED, bunch_new, bunch_free, bunch_recycle, bunch_claim, bunch_save, bunch_load, bunch_correct_ptr, bunch_unclaimed, BUNCH_CLAIMED

trish2/bunch_t, trish2/bunch_block_t [ Structures ]

[ Top ] [ Structures ]

NAME

bunch_t, bunch_block_t

SYNOPSIS

 #include <bunch.h>
 typedef struct {
   size_t element_size;
   int block_size;
   int block_number;
   bunch_block_t **blocks;
   int attrib;
 } bunch_t;

 typedef struct {
   intptr_t offset;
   unsigned int unclaimed;
   void *data;
 } bunch_block_t;

DESCRIPTION

The bunch_t and bunch_block_t structures contain allocated memory that can be claimed with bunch_claim. These structures are meant to be manipulated through functions defined in bunch.h exclusively. However we give their definitions, just in case.

ATTRIBUTES

Members of bunch_t:

Members of bunch_block_t:

SEE ALSO

bunch, BUNCH_PRUNED, bunch_new, bunch_load, bunch_unclaimed, BUNCH_CLAIMED

trish2/BUNCH_PRUNED [ Definitions ]

[ Top ] [ Definitions ]

NAME

BUNCH_PRUNED

SYNOPSIS

 #include <bunch.h>
 #define BUNCH_PRUNED

DESCRIPTION

BUNCH_PRUNED is used to indicate a bunch is pruned. A pruned bunch has no available elements.

SEE ALSO

bunch, bunch_t, bunch_recycle, bunch_claim, bunch_save, bunch_load, bunch_correct_ptr, bunch_unclaimed, BUNCH_CLAIMED

trish2/bunch_new [ Functions ]

[ Top ] [ Functions ]

NAME

bunch_new

SYNOPSIS

 #include <bunch.h>
 bunch_t *bunch_new(size_t element_size, unsigned int block_size);

FUNCTION

bunch_new allocates a new bunch_t structure and a single bunch_block_t structure with block_size elements of element_size bytes.

INPUTS

RETURN VALUE

A pointer to a freshly allocated bunch_t structure. NULL in the case the allocation failed.

SEE ALSO

bunch, bunch_t, bunch_free, bunch_recycle, bunch_claim

trish2/bunch_free [ Functions ]

[ Top ] [ Functions ]

NAME

bunch_new

SYNOPSIS

 #include <bunch.h>
 void bunch_free(bunch_t *b);

FUNCTION

bunch_free destroys the bunch b as well as all pointers claimed from it. If you try to access a pointer claimed from b after calling bunch_free, then tou will get a segmentation fault.

INPUTS

SEE ALSO

bunch, bunch_t, bunch_new, bunch_recycle

trish2/bunch_recycle [ Functions ]

[ Top ] [ Functions ]

NAME

bunch_recycle

SYNOPSIS

 #include <bunch.h>
 void bunch_recycle(bunch_t *b);

FUNCTION

bunch_recycle makes all memory allocated in bunch b available for claim. That means that future calls to bunch_claim may return memory segments already returned by call before bunch_recycle. So be sure you are not using claimed pointers anymore before recycling.

The memory is not initialized.

INPUTS

SEE ALSO

bunch, bunch_t, bunch_free, bunch_claim, bunch_correct_ptr, bunch_unclaimed, BUNCH_CLAIMED

trish2/bunch_claim [ Functions ]

[ Top ] [ Functions ]

NAME

bunch_claim

SYNOPSIS

 #include <bunch.h>
 void *bunch_claim(bunch_t *b, size_t nb);

FUNCTION

bunch_claim returns a pointer of nb contiguous elements from bunch b. The choice of a block containing enough available elements is done automatically. It is an error to claim more elements than the block size (set at the creation of b), or to claim from a pruned bunch.

The objects returned are guaranteed to not overlap with other claimed ones from the last call to bunch_recycle. You can use at your will, but if you exceed the memory you claimed, then the behaviour of totally undefined.

Claimed pointers are not meant to be freed directly with free(). All claimed pointers are freed when the bunch is destroyed with bunch_free.

INPUTS

RETURN VALUE

The pointer to unsused memory.

SEE ALSO

bunch, bunch_t, BUNCH_PRUNED, bunch_recycle

trish2/bunch_save [ Functions ]

[ Top ] [ Functions ]

NAME

bunch_claim

SYNOPSIS

 #include <bunch.h>
 void bunch_save(bunch_t *b, int options, FILE *f);

FUNCTION

bunch_save writes the data claimed in bunch b into file f. The writing is achieved with fwrite so it is your responsibility to remeber somehow the current file offset before calling bunch_save.

INPUTS

SEE ALSO

bunch, bunch_t, BUNCH_PRUNED, bunch_claim, bunch_load

trish2/bunch_load [ Functions ]

[ Top ] [ Functions ]

NAME

bunch_claim

SYNOPSIS

 #include <bunch.h>
 bunch_t *bunch_load(FILE *f);

FUNCTION

bunch_load reads a bunch from the file handler f. The bunch is allocated and filled with data held in f. If the file handler points to data that was not created by bunch_save, then the behaviour is utterly indefined. If the bunch was saved with the BUNCH_PRUNED option, then the bunch returned by bunch_load is pruned.

INPUTS

RETURN VALUE

A pointer to a freshly allocated and filled bunch.

SEE ALSO

bunch, bunch_t, BUNCH_PRUNED, bunch_new, bunch_free, bunch_save, bunch_correct_ptr

trish2/bunch_correct_ptr, trish2/BUNCH_CORRECT_PTR [ Functions ]

[ Top ] [ Functions ]

NAME

bunch_correct_ptr, BUNCH_CORRECT_PTR

SYNOPSIS

 #include <bunch.h>
 void *bunch_correct_ptr(bunch_t *b, void *p);
 #define BUNCH_CORRECT_PTR(b, p) (p) = bunch_correct_ptr((b), (p))

FUNCTION

bunch_correct_ptr computes the new address of a pointer claimed in a bunch that was created by bunch_load. Keep in mind that BUNCH_CORRECT_PTR is implemented as a macro so the arguments may be evaluated several times.

INPUTS

RETURN VALUE

The address to the actual location of the object.

SEE ALSO

bunch, bunch_t, BUNCH_PRUNED, bunch_recycle, bunch_claim, bunch_save, bunch_load

trish2/bunch_unclaimed [ Functions ]

[ Top ] [ Functions ]

NAME

bunch_unclaimed

SYNOPSIS

 #include <bunch.h>
 unsigned int bunch_unclaimed(bunch_t *b);

FUNCTION

bunch_unclaimed sums the availaible elements in all blocks of the bunch.

INPUTS

RETURN VALUE

The number of available elements. If the bunch is pruned, returns 0.

SEE ALSO

bunch, bunch_t, BUNCH_PRUNED, bunch_recycle, bunch_claim, BUNCH_CLAIMED

trish2/BUNCH_CLAIMED [ Functions ]

[ Top ] [ Functions ]

NAME

BUNCH_CLAIMED

SYNOPSIS

 #include <bunch.h>
 unsigned int BUNCH_CLAIMED(bunch_t *b);

FUNCTION

BUNCH_CLAIMED computes the total number of elements claimed in b. Implemented as a macro.

INPUTS

RETURN VALUE

The number of claimed elements.

SEE ALSO

bunch, bunch_t, BUNCH_PRUNED, bunch_recycle, bunch_claim, bunch_unclaimed