grapes / include / chunkidset.h @ master
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 */ |