Statistics
| Branch: | Revision:

grapes / include / chunkidset.h @ 438e6c03

History | View | Annotate | Download (3.8 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
 */
10
 
11
#ifndef CHUNKIDSET_H
12
#define CHUNKIDSET_H
13

    
14
/**
15
* Opaque data type representing a Chunk ID Set
16
*/
17
typedef struct chunkID_set ChunkIDSet;
18

    
19
#define CHUNKID_INVALID ((2^32) - 1)
20

    
21
 /**
22
  * @brief Allocate a chunk ID set.
23
  * 
24
  * Create an empty chunk ID set, and return a pointer to it.
25
  * 
26
  * @param config a configuration string containing tags which describe
27
  *                   the chunk ID set. For example, the "size" tag indicates
28
  *                   the expected number of chunk IDs that will be stored
29
  *                   in the set; 0 or not present if such a number is not
30
  *                   known.
31
  * @return the pointer to the new set on success, NULL on error
32
  */
33
struct chunkID_set *chunkID_set_init(const char *config);
34

    
35
 /**
36
  * @brief Add a chunk ID to the set.
37
  * 
38
  * Insert a chunk ID, and its associated priority (the priority is assumed
39
  * to depend on the insertion order), to the set. If the chunk
40
  * ID is already in the set, nothing happens.
41
  *
42
  * @param h a pointer to the set where the chunk ID has to be added
43
  * @param chunk_id the ID of the chunk to be inserted in the set
44
  * @return > 0 if the chunk ID is correctly inserted in the set, 0 if chunk_id
45
  *         is already in the set, < 0 on error
46
  */
47
int chunkID_set_add_chunk(struct chunkID_set *h, int chunk_id);
48

    
49
 /**
50
  * @brief Get the set size
51
  * 
52
  * Return the number of chunk IDs present in a set.
53
  *
54
  * @param h a pointer to the set
55
  * @return the number of chunk IDs in the set, or < 0 on error
56
  */
57
int chunkID_set_size(const struct chunkID_set *h);
58

    
59
 /**
60
  * @brief Get a chunk ID from a set
61
  * 
62
  * Return the i^th chunk ID from the set. The chunk's priority is
63
  * assumed to depend on i.
64
  *
65
  * @param h a pointer to the set
66
  * @param i the index of the chunk ID to be returned
67
  * @return the i^th chunk ID in the set in case of success, or < 0 on error
68
  *         (in case of error, priority is not meaningful)
69
  */
70
int chunkID_set_get_chunk(const struct chunkID_set *h, int i);
71

    
72
 /**
73
  * @brief Check if a chunk ID is in a set
74
  * 
75
  * @param h a pointer to the set
76
  * @param chunk_id the chunk ID we are searching for
77
  * @return the priority of the chunk ID if it is present in the set,
78
  *         < 0 on error or if the chunk ID is not in the set
79
  */
80
int chunkID_set_check(const struct chunkID_set *h, int chunk_id);
81

    
82
 /**
83
  * Add chunks from a chunk ID set to another one
84
  * 
85
  * Insert all chunk from a chunk ID set into another one. Priority is
86
  * kept in the old one. New chunks from the added one are added with
87
  * lower priorities, but keeping their order.
88
  *
89
  * @param h a pointer to the set where the chunk ID has to be added
90
  * @param a a pointer to the set which has to be added
91
  * @return > 0 if the chunk ID is correctly inserted in the set, 0 if chunk_id
92
  *         is already in the set, < 0 on error
93
  */
94
int chunkID_set_union(struct chunkID_set *h, struct chunkID_set *a);
95

    
96
 /**
97
  * Clear a set
98
  * 
99
  * Remove all the chunk IDs from a set.
100
  *
101
  * @param h a pointer to the set
102
  * @param size the expected number of chunk IDs that will be stored
103
  *                 in the set; 0 if such a number is not known.
104
  */
105
void chunkID_set_clear(struct chunkID_set *h, int size);
106

    
107
 /**
108
  * @brief Clear a set and free all associated memory.
109
  *
110
  * @param h a pointer to the set
111
  */
112
void chunkID_set_free(struct chunkID_set *h);
113

    
114
uint32_t chunkID_set_get_earliest(const struct chunkID_set *h);
115

    
116
uint32_t chunkID_set_get_latest(const struct chunkID_set *h);
117

    
118
#endif        /* CHUNKIDSET_H */