Statistics
| Branch: | Revision:

grapes / include / peerset.h @ b9e0d721

History | View | Annotate | Download (3.62 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
typedef struct peerset PeerSet;
15

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

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

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

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

    
67
 /**
68
  * Get a peer if it is in the set
69
  * 
70
  * @parameter h a pointer to the set
71
  * @parameter id the nodeID we are searching for
72
  * @return a pointer to the peer if it is present in the set,
73
  *         NULL if the peer is not in the set
74
  */
75
struct peer *peerset_get_peer(const struct peerset *h, const struct nodeID *id);
76

    
77
 /**
78
  * Get the set size
79
  * 
80
  * Return the number of peers present in a set.
81
  *
82
  * @parameter h a pointer to the set
83
  * @return the number of peers in the set, or < 0 on error
84
  */
85
int peerset_size(const struct peerset *h);
86

    
87
 /**
88
  * Get a peer from a set
89
  * 
90
  * Return the peers of the set. The peer's priority is
91
  * assumed to depend on i.
92
  *
93
  * @parameter h a pointer to the set
94
  * @return the list of peer structures
95
  */
96
struct peer *peerset_get_peers(const struct peerset *h);
97

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

    
108

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

    
120
#endif        /* PEERSET_H */