grapes / include / peerset.h @ master
History | View | Annotate | Download (4.06 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 |
void peerset_destroy(struct peerset **h); |
21 |
|
22 |
#define peerset_for_each(pset,p,i) \
|
23 |
for(i=0,p= peerset_size(pset) > 0 ? ((struct peer const *)peerset_get_peers(pset)[0]) : NULL; i<peerset_size(pset);i++,p=((struct peer const *)peerset_get_peers(pset)[i])) |
24 |
|
25 |
/**
|
26 |
* @brief Allocate a peer set.
|
27 |
*
|
28 |
* Create an empty peer set, and return a pointer to it.
|
29 |
*
|
30 |
* @param config a string containing tags which describe the peerset.
|
31 |
* For example, the "size" tag indicates the expected
|
32 |
* number of peers that will be stored in the set;
|
33 |
* 0 or not present if such a number is not known.
|
34 |
* @return the pointer to the new set on success, NULL on error
|
35 |
*/
|
36 |
struct peerset *peerset_init(const char *config); |
37 |
|
38 |
/**
|
39 |
* @brief Add a peer to the set.
|
40 |
*
|
41 |
* Insert a peer to the set, creating the peer structure. If the peer
|
42 |
* is already in the set, nothing happens.
|
43 |
*
|
44 |
* @param h a pointer to the set where the peer has to be added
|
45 |
* @param id the ID of the peer to be inserted in the set
|
46 |
* @return > 0 if the peer is correctly inserted in the set, 0 if a peer with
|
47 |
* the same nodeID is already in the set, < 0 on error
|
48 |
*/
|
49 |
int peerset_add_peer(struct peerset *h,const struct nodeID *id); |
50 |
|
51 |
/**
|
52 |
* @brief Add peers to the set.
|
53 |
*
|
54 |
* Comodity function to add several peers at the same time to the set.
|
55 |
* See peerset_add_peer
|
56 |
*
|
57 |
* @param h a pointer to the set where the peer has to be added
|
58 |
* @param ids the IDs of the peers to be inserted in the set
|
59 |
* @param n length of the its array
|
60 |
*/
|
61 |
void peerset_add_peers(struct peerset *h, struct nodeID **ids, int n); |
62 |
|
63 |
/**
|
64 |
* @brief Remove a peer from the set.
|
65 |
*
|
66 |
* Remove a peer from the set, distroying all associated data.
|
67 |
* If peer exists, pointers of peerset_get_peers move backwards.
|
68 |
*
|
69 |
* @param h a pointer to the set where the peer has to be added
|
70 |
* @param id the ID of the peer to be removed from the set
|
71 |
* @return > 0 if the peer is correctly removed from the set,
|
72 |
* < 0 on error
|
73 |
*/
|
74 |
int peerset_remove_peer(struct peerset *h, const struct nodeID *id); |
75 |
|
76 |
/**
|
77 |
* @brief Get a peer if it is in the set
|
78 |
*
|
79 |
* @param h a pointer to the set
|
80 |
* @param id the nodeID we are searching for
|
81 |
* @return a pointer to the peer if it is present in the set,
|
82 |
* NULL if the peer is not in the set
|
83 |
*/
|
84 |
struct peer *peerset_get_peer(const struct peerset *h, const struct nodeID *id); |
85 |
|
86 |
/**
|
87 |
* @brief Get the set size
|
88 |
*
|
89 |
* Return the number of peers present in a set.
|
90 |
*
|
91 |
* @param h a pointer to the set
|
92 |
* @return the number of peers in the set, or < 0 on error
|
93 |
*/
|
94 |
int peerset_size(const struct peerset *h); |
95 |
|
96 |
/**
|
97 |
* @brief Get a peer from a set
|
98 |
*
|
99 |
* Return the peers of the set. The peer's priority is
|
100 |
* assumed to depend on i.
|
101 |
*
|
102 |
* @param h a pointer to the set
|
103 |
* @return the list of peer structures
|
104 |
*/
|
105 |
struct peer **peerset_get_peers(const struct peerset *h); |
106 |
|
107 |
/**
|
108 |
* @brief Check if a peer is in a set
|
109 |
*
|
110 |
* @param h a pointer to the set
|
111 |
* @param id the nodeID we are searching for
|
112 |
* @return the position of the peer if it is present in the set,
|
113 |
* < 0 on error or if the peer is not in the set
|
114 |
*/
|
115 |
int peerset_check(const struct peerset *h, const struct nodeID *id); |
116 |
|
117 |
|
118 |
/**
|
119 |
* @brief Clear a set
|
120 |
*
|
121 |
* Remove all the peers from a set.
|
122 |
*
|
123 |
* @param h a pointer to the set
|
124 |
* @param size the expected number of peers that will be stored
|
125 |
* in the set; 0 if such a number is not known.
|
126 |
*/
|
127 |
void peerset_clear(struct peerset *h, int size); |
128 |
|
129 |
int peerset_push_peer(struct peerset *h, struct peer *e); |
130 |
|
131 |
struct peer * peerset_pop_peer(struct peerset *h, const struct nodeID *id); |
132 |
|
133 |
#endif /* PEERSET_H */ |