Statistics
| Branch: | Revision:

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 */