Statistics
| Branch: | Revision:

grapes / include / chunkidset.h @ 8d11c217

History | View | Annotate | Download (4.48 KB)

1
/** @file chunkidset.h
2
 *
3
 * @brief Structure containing a set of chunk IDs.
4
 *
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
 * 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
 */
18
 
19
#ifndef CHUNKIDSET_H
20
#define CHUNKIDSET_H
21

    
22
/**
23
* Opaque data type representing a Chunk ID Set
24
*/
25
typedef struct chunkID_set ChunkIDSet;
26

    
27
#define CHUNKID_INVALID (uint32_t)-1        /**< Trying to get a chunk ID from an empty set */
28

    
29
 /**
30
  * @brief Allocate a chunk ID set.
31
  * 
32
  * Create an empty chunk ID set, and return a pointer to it.
33
  * 
34
  * @param config a configuration string containing tags which describe
35
  *                   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
  * @return the pointer to the new set on success, NULL on error
40
  */
41
struct chunkID_set *chunkID_set_init(const char *config);
42

    
43
 /**
44
  * @brief Add a chunk ID to the set.
45
  * 
46
  * 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
  * ID is already in the set, nothing happens.
49
  *
50
  * @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
  * @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
int chunkID_set_add_chunk(struct chunkID_set *h, int chunk_id);
56

    
57
 /**
58
  * @brief Get the set size
59
  * 
60
  * Return the number of chunk IDs present in a set.
61
  *
62
  * @param h a pointer to the set
63
  * @return the number of chunk IDs in the set, or < 0 on error
64
  */
65
int chunkID_set_size(const struct chunkID_set *h);
66

    
67
 /**
68
  * @brief Get a chunk ID from a set
69
  * 
70
  * Return the i^th chunk ID from the set. The chunk's priority is
71
  * assumed to depend on i.
72
  *
73
  * @param h a pointer to the set
74
  * @param i the index of the chunk ID to be returned
75
  * @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
int chunkID_set_get_chunk(const struct chunkID_set *h, int i);
79

    
80
 /**
81
  * @brief Check if a chunk ID is in a set
82
  * 
83
  * @param h a pointer to the set
84
  * @param chunk_id the chunk ID we are searching for
85
  * @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
  * 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
  * @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
  * @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
  * Clear a set
106
  * 
107
  * Remove all the chunk IDs from a set.
108
  *
109
  * @param h a pointer to the set
110
  * @param size the expected number of chunk IDs that will be stored
111
  *                 in the set; 0 if such a number is not known.
112
  */
113
void chunkID_set_clear(struct chunkID_set *h, int size);
114

    
115
 /**
116
  * @brief Clear a set and free all associated memory.
117
  *
118
  * @param h a pointer to the set
119
  */
120
void chunkID_set_free(struct chunkID_set *h);
121

    
122
 /**
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
uint32_t chunkID_set_get_earliest(const struct chunkID_set *h);
131

    
132
 /**
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
uint32_t chunkID_set_get_latest(const struct chunkID_set *h);
141

    
142
#endif        /* CHUNKIDSET_H */