Statistics
| Branch: | Revision:

grapes / include / chunkidset.h @ c5922d21

History | View | Annotate | Download (4.54 KB)

1 6ce199d9 Luca
/** @file chunkidset.h
2
 *
3 7fcd5e5c MarcoBiazzini
 * @brief Structure containing a set of chunk IDs.
4 6ce199d9 Luca
 *
5
 * The Chunk ID Set is an abstract data structure that can contain a set of
6
 * (chunk ID, priority) couples. Few simple operations for adding chunk IDs
7
 * in a set, for getting the chunk IDs present in a set, for allocating a
8
 * set, and for clearing a set are provided.
9 e38ca866 Luca Abeni
 * See @link chunkidset_test.c chunkidset_test.c @endlink for an usage example.
10
 *
11
 */
12
13
/** @example chunkidset_test.c
14
 * 
15
 * A test program showing how to use the Chunk ID Set API.
16
 *
17 6ce199d9 Luca
 */
18
 
19 408ab77c Luca
#ifndef CHUNKIDSET_H
20
#define CHUNKIDSET_H
21
22 4affd2bf MarcoBiazzini
/**
23
* Opaque data type representing a Chunk ID Set
24
*/
25 408ab77c Luca
typedef struct chunkID_set ChunkIDSet;
26
27 8d11c217 Luca Abeni
#define CHUNKID_INVALID (uint32_t)-1        /**< Trying to get a chunk ID from an empty set */
28 438e6c03 Luca Abeni
29 6ce199d9 Luca
 /**
30 9e4a282c MarcoBiazzini
  * @brief Allocate a chunk ID set.
31 6ce199d9 Luca
  * 
32
  * Create an empty chunk ID set, and return a pointer to it.
33
  * 
34 4affd2bf MarcoBiazzini
  * @param config a configuration string containing tags which describe
35 ea821d90 Csaba Kiraly
  *                   the chunk ID set. For example, the "size" tag indicates
36
  *                   the expected number of chunk IDs that will be stored
37
  *                   in the set; 0 or not present if such a number is not
38
  *                   known.
39 6ce199d9 Luca
  * @return the pointer to the new set on success, NULL on error
40
  */
41 ea821d90 Csaba Kiraly
struct chunkID_set *chunkID_set_init(const char *config);
42 6ce199d9 Luca
43
 /**
44 9e4a282c MarcoBiazzini
  * @brief Add a chunk ID to the set.
45 6ce199d9 Luca
  * 
46 286ee331 Luca Abeni
  * Insert a chunk ID, and its associated priority (the priority is assumed
47
  * to depend on the insertion order), to the set. If the chunk
48 6ce199d9 Luca
  * ID is already in the set, nothing happens.
49
  *
50 4affd2bf MarcoBiazzini
  * @param h a pointer to the set where the chunk ID has to be added
51
  * @param chunk_id the ID of the chunk to be inserted in the set
52 6ce199d9 Luca
  * @return > 0 if the chunk ID is correctly inserted in the set, 0 if chunk_id
53
  *         is already in the set, < 0 on error
54
  */
55 286ee331 Luca Abeni
int chunkID_set_add_chunk(struct chunkID_set *h, int chunk_id);
56 6ce199d9 Luca
57
 /**
58 9e4a282c MarcoBiazzini
  * @brief Get the set size
59 6ce199d9 Luca
  * 
60
  * Return the number of chunk IDs present in a set.
61
  *
62 4affd2bf MarcoBiazzini
  * @param h a pointer to the set
63 6ce199d9 Luca
  * @return the number of chunk IDs in the set, or < 0 on error
64
  */
65 f3480090 CsabaKiraly
int chunkID_set_size(const struct chunkID_set *h);
66 6ce199d9 Luca
67
 /**
68 9e4a282c MarcoBiazzini
  * @brief Get a chunk ID from a set
69 6ce199d9 Luca
  * 
70 286ee331 Luca Abeni
  * Return the i^th chunk ID from the set. The chunk's priority is
71
  * assumed to depend on i.
72 6ce199d9 Luca
  *
73 4affd2bf MarcoBiazzini
  * @param h a pointer to the set
74
  * @param i the index of the chunk ID to be returned
75 6ce199d9 Luca
  * @return the i^th chunk ID in the set in case of success, or < 0 on error
76
  *         (in case of error, priority is not meaningful)
77
  */
78 286ee331 Luca Abeni
int chunkID_set_get_chunk(const struct chunkID_set *h, int i);
79 6ce199d9 Luca
80
 /**
81 9e4a282c MarcoBiazzini
  * @brief Check if a chunk ID is in a set
82 6ce199d9 Luca
  * 
83 4affd2bf MarcoBiazzini
  * @param h a pointer to the set
84
  * @param chunk_id the chunk ID we are searching for
85 6ce199d9 Luca
  * @return the priority of the chunk ID if it is present in the set,
86
  *         < 0 on error or if the chunk ID is not in the set
87
  */
88
int chunkID_set_check(const struct chunkID_set *h, int chunk_id);
89
90
 /**
91 a2971dec CsabaKiraly
  * Add chunks from a chunk ID set to another one
92
  * 
93
  * Insert all chunk from a chunk ID set into another one. Priority is
94
  * kept in the old one. New chunks from the added one are added with
95
  * lower priorities, but keeping their order.
96
  *
97 4affd2bf MarcoBiazzini
  * @param h a pointer to the set where the chunk ID has to be added
98
  * @param a a pointer to the set which has to be added
99 a2971dec CsabaKiraly
  * @return > 0 if the chunk ID is correctly inserted in the set, 0 if chunk_id
100
  *         is already in the set, < 0 on error
101
  */
102
int chunkID_set_union(struct chunkID_set *h, struct chunkID_set *a);
103
104
 /**
105 6ce199d9 Luca
  * Clear a set
106
  * 
107
  * Remove all the chunk IDs from a set.
108
  *
109 4affd2bf MarcoBiazzini
  * @param h a pointer to the set
110
  * @param size the expected number of chunk IDs that will be stored
111 286ee331 Luca Abeni
  *                 in the set; 0 if such a number is not known.
112 6ce199d9 Luca
  */
113 f3480090 CsabaKiraly
void chunkID_set_clear(struct chunkID_set *h, int size);
114 408ab77c Luca
115 8484348e Csaba Kiraly
 /**
116 9e4a282c MarcoBiazzini
  * @brief Clear a set and free all associated memory.
117 8484348e Csaba Kiraly
  *
118 4affd2bf MarcoBiazzini
  * @param h a pointer to the set
119 8484348e Csaba Kiraly
  */
120
void chunkID_set_free(struct chunkID_set *h);
121
122 8d11c217 Luca Abeni
 /**
123
  * @brief Get the smallest chunk ID from a set
124
  * 
125
  * Return the ID of the earliest chunk from the the set.
126
  *
127
  * @param h a pointer to the set
128
  * @return the chunk ID in case of success, or CHUNKID_INVALID on error
129
  */
130 438e6c03 Luca Abeni
uint32_t chunkID_set_get_earliest(const struct chunkID_set *h);
131 f621745b Csaba Kiraly
132 8d11c217 Luca Abeni
 /**
133
  * @brief Get the largest chunk ID from a set
134
  * 
135
  * Return the ID of the latest chunk from the the set.
136
  *
137
  * @param h a pointer to the set
138
  * @return the chunk ID in case of success, or CHUNKID_INVALID on error
139
  */
140 438e6c03 Luca Abeni
uint32_t chunkID_set_get_latest(const struct chunkID_set *h);
141 f621745b Csaba Kiraly
142 c8a9504f Csaba Kiraly
void chunkID_set_trim(struct chunkID_set *h, int size);
143
144 408ab77c Luca
#endif        /* CHUNKIDSET_H */