summaryrefslogtreecommitdiff
path: root/cesar/lib/blk_table.h
blob: 4e0b0f614bf1dea36ed3e79206e41d17ae96d057 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
#ifndef lib_blk_table_h
#define lib_blk_table_h
/* Cesar project {{{
 *
 * Copyright (C) 2007 Spidcom
 *
 * <<<Licence>>>
 *
 * }}} */
/**
 * \file    lib/blk_table.h
 * \brief   Manipulate table using blk storage.
 * \ingroup lib
 *
 * Block allocated table
 * =====================
 *
 * This entity provide a way to allocate a table and manipulate it's elements.
 * As you can't use malloc to create a dynamic array, you may allocate several
 * blocks of BLK_SIZE using blk library but the accessibility of the stored
 * data may not be easy. blk_table library make easier the storage of a
 * dynamic array by creating a virtual array who can be read and written.
 */

/** Table descriptor. */
struct blk_table_t
{
    /** Size of the stored type. */
    u8 type_size;
    /** Total number of elements. */
    u16 size;
    /** Pointer to the first blk block. */
    blk_t *first_blk;
    /** Total number of allocated blk blocks. */
    u8 blk_nb;
    /** Pointer to user's data. */
    u8 *data[0];
};
typedef struct blk_table_t blk_table_t;

BEGIN_DECLS

/**
 * Allocate a new table of elements.
 * \param  type_size  size in octet of the type stored in table.
 * BLK_SIZE % type_size must be equal to zero and inferior or equal to
 * BLK_SIZE.
 * \param  max  max number of items of this type.
 * \return  a pointer to blk_table informations.
 *
 * \code
 * // Example of a table containing 3000 u16.
 * blk_table_t *tab = blk_table_init (sizeof (u16), 3000);
 * \endcode
 */
blk_table_t *
blk_table_init (uint type_size, uint max);

/**
 * Free table.
 * \param  tab  pointer of table to free.
 */
void
blk_table_free (blk_table_t *tab);

/**
 * Get a pointer to a value in the table.
 * \param  tab  pointer to the table.
 * \param  index  index of the data to read on the table.
 * \return  address where data is stored.
 *
 * \code
 * blk_table_t *tab = blk_table_init (sizeof (u16), 100);
 * u16 *i = (u16 *) blk_table_get (tab, 42);
 * dbg_assert (i);
 * // Then you can read/write value.
 * *i = 51;
 * \endcode
 */
void *
blk_table_get (blk_table_t *tab, uint index);

END_DECLS

#endif /* lib_blk_table_h */