Statistics
| Branch: | Revision:

grapes / include / peerset.h @ d1de8494

History | View | Annotate | Download (3.43 KB)

1
/** @file peerset.h
2
 *
3
 * Peer Set
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 size the expected number of peers that will be stored
22
  *                 in the set; 0 if such a number is not known.
23
  * @return the pointer to the new set on success, NULL on error
24
  */
25
struct peerset *peerset_init(int size);
26

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

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

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

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

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

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

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

    
106

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

    
118
#endif        /* PEERSET_H */