## 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 */ |