Statistics
| Branch: | Revision:

grapes / include / peersampler.h @ master

History | View | Annotate | Download (6.5 KB)

1 efeaec84 Luca Abeni
#ifndef PEERSAMPLER_H
2
#define PEERSAMPLER_H
3
4
/** @file peersampler.h 
5
 *
6
 * @brief Peer Sampler interface.
7
 *
8
 * This is the Peer Sampler interface. See @link topology_test.c
9 62f68831 Luca Abeni
 * topology_test.c @endlink for a simple usage example, 
10
 * @link topology_test_th.c topology_test_th.c @endlink for an
11
 * example using multiple threads, and @link topology_test_attr.c
12
 * topology_test_attr.c @endlink for an example with metadata.
13 efeaec84 Luca Abeni
 *
14
 */
15
16
/** @example topology_test.c
17
 * 
18 62f68831 Luca Abeni
 * A simple example showing how to use the Peer Sampler API.
19
 *
20
 */
21
22
/** @example topology_test_th.c
23
 * 
24
 * An example showing how to use the Peer Sampler API with multiple threads.
25
 *
26
 */
27
28
/** @example topology_test_attr.c
29
 * 
30
 * An example showing how to use the Peer Sampler API with peers' attributes
31
 * (metadata).
32 efeaec84 Luca Abeni
 *
33
 */
34
35
36
/**
37 6d3a033f Luca
   @brief Mantains the context of a topology manager instance
38
 */
39 eb607b63 Luca
struct psample_context;
40 6d3a033f Luca
41
/**
42 efeaec84 Luca Abeni
  @brief Get a sample of the active peers.
43

44
  This function returns the current peer sampler cache (i.e., the set of
45
  known peers), and its size. Note that the current cache 
46
  size can be different from the requested one, because of how the peer 
47
  sampling protocols work. 
48

49 6d3a033f Luca
  @param tc the pointer to the current topology manager instance context
50 efeaec84 Luca Abeni
  @param n pointer to an integer where the cache size is returned.
51
           Is set to -1 in case of error, or 0 if the cache is empty.
52
  @return a pointer to an array of nodeID describing a random view of the system. NULL
53
          in case of error, or if the cache is empty.
54
*/
55 92358b75 Luca Abeni
const struct nodeID *const *psample_get_cache(struct psample_context *tc, int *n);
56 efeaec84 Luca Abeni
57
/**
58
  @brief Get the peer's metadata.
59

60
  Each known peer can have some opaque metadata attached to
61
  it, and such metadata is gossiped together with the nodeIDs.
62
  This function returns the metadata currently associated to the
63
  known peers, and the size of each object composing the metadata
64
  (metadata have the same structure for all the peers, so such size is
65
  constant). The number of known peers (cache size) can be known by calling
66
  psample_get_cache().
67

68 6d3a033f Luca
  @param tc the pointer to the current topology manager instance context
69 efeaec84 Luca Abeni
  @param metadata_size pointer to an integer where the size of the metadata
70
         associated to each peer is returned.
71
         Is set to -1 in case of error, or 0 if the cache is empty.
72
  @return a pointer to an array of metadata (ordered as the peers returned
73
          by psample_get_cache()).
74
          NULL in case of error, or if the cache is empty.
75
*/
76 eb607b63 Luca
const void *psample_get_metadata(struct psample_context *tc, int *metadata_size);
77 efeaec84 Luca Abeni
78
/**
79
  @brief Increase the cache size.
80

81
  This function can be used to increase the number of known peers (that is,
82
       the degree of the overlay graph) by a specified amount.
83 6d3a033f Luca
  @param tc the pointer to the current topology manager instance context
84 efeaec84 Luca Abeni
  @param n number of peers by which the cache size must be incremented.
85
  @return the new cache size in case of success; -1 in case of error.
86
*/
87 eb607b63 Luca
int psample_grow_cache(struct psample_context *tc, int n);
88 efeaec84 Luca Abeni
89
/**
90
  @brief Decrease the cache size.
91

92
  This function can be used to reduce the number of known peers (that is,
93
       the degree of the overlay graph) by a specified amount.
94 6d3a033f Luca
  @param tc the pointer to the current topology manager instance context
95 efeaec84 Luca Abeni
  @param n number of peers by which the cache size must be decreased.
96
  @return the new cache size in case of success; -1 in case of error.
97
*/
98 eb607b63 Luca
int psample_shrink_cache(struct psample_context *tc, int n);
99 efeaec84 Luca Abeni
100
/**
101
  @brief Remove a peer from the cache.
102

103
  This function can be used to remove a specified peer from the
104
  cache. Note that the requested cache size is not
105
  modified, so the peer will be soon replaced by a different one.
106 6d3a033f Luca
  @param tc the pointer to the current topology manager instance context
107 efeaec84 Luca Abeni
  @param neighbour the id of the peer to be removed from the
108
         cache.
109
  @return 0 in case of success; -1 in case of error.
110
*/
111 15d5934d Luca Abeni
int psample_remove_peer(struct psample_context *tc, const struct nodeID *neighbour);
112 efeaec84 Luca Abeni
113
/**
114
  @brief Change the metadata.
115

116
  This function can be used to modify/update the metadata for a
117
  peer. Because of security concerns, only the metadata for the
118
  local peer can be modified.
119 6d3a033f Luca
  @param tc the pointer to the current topology manager instance context
120 efeaec84 Luca Abeni
  @param metadata pointer to the new metadata associated to the peer (will be
121
         gossiped).
122
  @param metadata_size size of the metadata associated to the peer (must
123
         be the same as for the other peers).
124
  @return 0 in case of success; -1 in case of error.
125
*/
126 15d5934d Luca Abeni
int psample_change_metadata(struct psample_context *tc, const void *metadata, int metadata_size);
127 efeaec84 Luca Abeni
128
/**
129
  @brief Initialise the Peer Sampler.
130

131
  @param myID the ID of this peer.
132
  @param metadata pointer to the metadata associated to this peer (will be
133
         gossiped).
134
  @param metadata_size size of the metadata associated to this peer.
135 64130672 Luca Abeni
  @param config configuration parameter for the peer sampling module (specifying the
136
         peer sampling algorithm, the cache size, etc...)
137 6d3a033f Luca
  @return the topology manager context in case of success; NULL in case of error.
138 efeaec84 Luca Abeni
*/
139 15d5934d Luca Abeni
struct psample_context *psample_init(struct nodeID *myID, const void *metadata, int metadata_size, const char *config);
140 efeaec84 Luca Abeni
141
/**
142
  @brief Insert a known peer in the cache.
143

144
  This function can be used to add a specified peer to the
145
  cache. It is useful in the bootstrap phase.
146 6d3a033f Luca
  @param tc the pointer to the current topology manager instance context
147 efeaec84 Luca Abeni
  @param neighbour the id of the peer to be added to the
148
         cache.
149
  @param metadata pointer to the metadata associated to the new peer (will be
150
         gossiped).
151
  @param metadata_size size of the metadata associated to the new peer (must
152
         be the same as for the other peers).
153
  @return 0 in case of success; -1 in case of error.
154
*/
155 15d5934d Luca Abeni
int psample_add_peer(struct psample_context *tc, struct nodeID *neighbour, const void *metadata, int metadata_size);
156 efeaec84 Luca Abeni
157
/**
158
  @brief Pass a received packet to the Peer Sampler.
159

160
  This function passes to the Peer Sampler a packet that has
161
  been received from the network. The Peer Sampler will parse
162
  such packet and run the protocol, adding or removing peers to the
163
  cache, and sending peer sampling messages to other peers.
164 6d3a033f Luca
  @param tc the pointer to the current topology manager instance context
165 efeaec84 Luca Abeni
  @param buff a memory buffer containing the received message.
166
  @param len the size of such a memory buffer.
167
  @return 0 in case of success; -1 in case of error.
168
*/
169 eb607b63 Luca
int psample_parse_data(struct psample_context *tc, const uint8_t *buff, int len);
170 efeaec84 Luca Abeni
171 10ddaca7 Luca Baldesi
void psample_destroy(struct psample_context **context);
172 efeaec84 Luca Abeni
#endif /* PEERSAMPLER_H */