Statistics
| Branch: | Revision:

grapes / include / peerset.h @ master

History | View | Annotate | Download (4.06 KB)

1 47f2affa CsabaKiraly
/** @file peerset.h
2
 *
3 b9e0d721 MarcoBiazzini
 * @brief Structure containing a set of peers.
4 47f2affa CsabaKiraly
 *
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 a40a8d81 MarcoBiazzini
15
/**
16
* Opaque data type representing a Peer Set
17
*/
18 47f2affa CsabaKiraly
typedef struct peerset PeerSet;
19
20 41012841 Luca Baldesi
void peerset_destroy(struct peerset **h);
21
22
#define peerset_for_each(pset,p,i) \
23 67700aad Luca Baldesi
                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 41012841 Luca Baldesi
25 47f2affa CsabaKiraly
 /**
26 85c4b598 MarcoBiazzini
  * @brief Allocate a  peer set.
27 47f2affa CsabaKiraly
  * 
28
  * Create an empty peer set, and return a pointer to it.
29
  * 
30 a40a8d81 MarcoBiazzini
  * @param config a string containing tags which describe the peerset.
31 04df3b0f Luca
  *                   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 47f2affa CsabaKiraly
  * @return the pointer to the new set on success, NULL on error
35
  */
36 04df3b0f Luca
struct peerset *peerset_init(const char *config);
37 47f2affa CsabaKiraly
38
 /**
39 85c4b598 MarcoBiazzini
  * @brief Add a peer to the set.
40 47f2affa CsabaKiraly
  * 
41
  * Insert a peer to the set, creating the peer structure. If the peer
42
  * is already in the set, nothing happens.
43
  *
44 a40a8d81 MarcoBiazzini
  * @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 47f2affa CsabaKiraly
  * @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 fe3ab307 Luca Baldesi
int peerset_add_peer(struct peerset *h,const  struct nodeID *id);
50 47f2affa CsabaKiraly
51
 /**
52 85c4b598 MarcoBiazzini
  * @brief Add peers to the set.
53 13c9731e CsabaKiraly
  * 
54
  * Comodity function to add several peers at the same time to the set.
55
  * See peerset_add_peer
56
  *
57 a40a8d81 MarcoBiazzini
  * @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 13c9731e CsabaKiraly
  */
61 d1de8494 Luca Abeni
void peerset_add_peers(struct peerset *h, struct nodeID **ids, int n);
62 13c9731e CsabaKiraly
63
 /**
64 85c4b598 MarcoBiazzini
  * @brief Remove a peer from the set.
65 9e6eebab Csaba Kiraly
  * 
66
  * Remove a peer from the set, distroying all associated data.
67
  * If peer exists, pointers of peerset_get_peers move backwards.
68
  *
69 a40a8d81 MarcoBiazzini
  * @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 9e6eebab Csaba Kiraly
  * @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 85c4b598 MarcoBiazzini
  * @brief Get a peer if it is in the set
78 47f2affa CsabaKiraly
  * 
79 a40a8d81 MarcoBiazzini
  * @param h a pointer to the set
80
  * @param id the nodeID we are searching for
81 47f2affa CsabaKiraly
  * @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 060267cd Luca Abeni
struct peer *peerset_get_peer(const struct peerset *h, const struct nodeID *id);
85 47f2affa CsabaKiraly
86
 /**
87 85c4b598 MarcoBiazzini
  * @brief Get the set size
88 47f2affa CsabaKiraly
  * 
89
  * Return the number of peers present in a set.
90
  *
91 a40a8d81 MarcoBiazzini
  * @param h a pointer to the set
92 47f2affa CsabaKiraly
  * @return the number of peers in the set, or < 0 on error
93
  */
94
int peerset_size(const struct peerset *h);
95
96
 /**
97 85c4b598 MarcoBiazzini
  * @brief Get a peer from a set
98 47f2affa CsabaKiraly
  * 
99
  * Return the peers of the set. The peer's priority is
100
  * assumed to depend on i.
101
  *
102 a40a8d81 MarcoBiazzini
  * @param h a pointer to the set
103 47f2affa CsabaKiraly
  * @return the list of peer structures
104
  */
105 82438fe3 Luca Abeni
struct peer **peerset_get_peers(const struct peerset *h);
106 47f2affa CsabaKiraly
107
 /**
108 85c4b598 MarcoBiazzini
  * @brief Check if a peer is in a set
109 47f2affa CsabaKiraly
  * 
110 a40a8d81 MarcoBiazzini
  * @param h a pointer to the set
111
  * @param id the nodeID we are searching for
112 47f2affa CsabaKiraly
  * @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 c552e22d CsabaKiraly
int peerset_check(const struct peerset *h, const struct nodeID *id);
116 47f2affa CsabaKiraly
117
118
 /**
119 85c4b598 MarcoBiazzini
  * @brief Clear a set
120 47f2affa CsabaKiraly
  * 
121
  * Remove all the peers from a set.
122
  *
123 a40a8d81 MarcoBiazzini
  * @param h a pointer to the set
124
  * @param size the expected number of peers that will be stored
125 47f2affa CsabaKiraly
  *                 in the set; 0 if such a number is not known.
126
  */
127
void peerset_clear(struct peerset *h, int size);
128
129 c5922d21 Luca Abeni
int peerset_push_peer(struct peerset *h, struct peer *e);
130 91566cec Luca Baldesi
131
struct peer * peerset_pop_peer(struct peerset *h, const struct nodeID *id);
132
133 47f2affa CsabaKiraly
#endif        /* PEERSET_H */