Statistics
| Branch: | Revision:

grapes / include / peerset.h @ 82438fe3

History | View | Annotate | Download (3.67 KB)

1
/** @file peerset.h
2
 *
3
 * @brief Structure containing a set of peers.
4
 *
5
 * The Peer Set is an abstract data structure that can contain a set of
6
 * peer structures. It handles peers by their nodeIDs. Peer structures
7
 * are created and accessed based on their nodeID (i.e. unique address).
8
 *
9
 */
10
 
11
#ifndef PEERSET_H
12
#define PEERSET_H
13

    
14

    
15
/**
16
* Opaque data type representing a Peer Set
17
*/
18
typedef struct peerset PeerSet;
19

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

    
33
 /**
34
  * @brief Add a peer to the set.
35
  * 
36
  * Insert a peer to the set, creating the peer structure. If the peer
37
  * is already in the set, nothing happens.
38
  *
39
  * @param h a pointer to the set where the peer has to be added
40
  * @param id the ID of the peer to be inserted in the set
41
  * @return > 0 if the peer is correctly inserted in the set, 0 if a peer with
42
  *         the same nodeID is already in the set, < 0 on error
43
  */
44
int peerset_add_peer(struct peerset *h, struct nodeID *id);
45

    
46
 /**
47
  * @brief Add peers to the set.
48
  * 
49
  * Comodity function to add several peers at the same time to the set.
50
  * See peerset_add_peer
51
  *
52
  * @param h a pointer to the set where the peer has to be added
53
  * @param ids the IDs of the peers to be inserted in the set
54
  * @param n length of the its array
55
  */
56
void peerset_add_peers(struct peerset *h, struct nodeID **ids, int n);
57

    
58
 /**
59
  * @brief Remove a peer from the set.
60
  * 
61
  * Remove a peer from the set, distroying all associated data.
62
  * If peer exists, pointers of peerset_get_peers move backwards.
63
  *
64
  * @param h a pointer to the set where the peer has to be added
65
  * @param id the ID of the peer to be removed from the set
66
  * @return > 0 if the peer is correctly removed from the set,
67
  *         < 0 on error
68
  */
69
int peerset_remove_peer(struct peerset *h, const struct nodeID *id);
70

    
71
 /**
72
  * @brief Get a peer if it is in the set
73
  * 
74
  * @param h a pointer to the set
75
  * @param id the nodeID we are searching for
76
  * @return a pointer to the peer if it is present in the set,
77
  *         NULL if the peer is not in the set
78
  */
79
struct peer *peerset_get_peer(const struct peerset *h, const struct nodeID *id);
80

    
81
 /**
82
  * @brief Get the set size
83
  * 
84
  * Return the number of peers present in a set.
85
  *
86
  * @param h a pointer to the set
87
  * @return the number of peers in the set, or < 0 on error
88
  */
89
int peerset_size(const struct peerset *h);
90

    
91
 /**
92
  * @brief Get a peer from a set
93
  * 
94
  * Return the peers of the set. The peer's priority is
95
  * assumed to depend on i.
96
  *
97
  * @param h a pointer to the set
98
  * @return the list of peer structures
99
  */
100
struct peer **peerset_get_peers(const struct peerset *h);
101

    
102
 /**
103
  * @brief Check if a peer is in a set
104
  * 
105
  * @param h a pointer to the set
106
  * @param id the nodeID we are searching for
107
  * @return the position of the peer if it is present in the set,
108
  *         < 0 on error or if the peer is not in the set
109
  */
110
int peerset_check(const struct peerset *h, const struct nodeID *id);
111

    
112

    
113
 /**
114
  * @brief Clear a set
115
  * 
116
  * Remove all the peers from a set.
117
  *
118
  * @param h a pointer to the set
119
  * @param size the expected number of peers that will be stored
120
  *                 in the set; 0 if such a number is not known.
121
  */
122
void peerset_clear(struct peerset *h, int size);
123

    
124
#endif        /* PEERSET_H */