Statistics
| Branch: | Revision:

grapes / include / peersampler.h @ master

History | View | Annotate | Download (6.5 KB)

1
#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
 * 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
 *
14
 */
15

    
16
/** @example topology_test.c
17
 * 
18
 * 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
 *
33
 */
34

    
35

    
36
/**
37
   @brief Mantains the context of a topology manager instance
38
 */
39
struct psample_context;
40

    
41
/**
42
  @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
  @param tc the pointer to the current topology manager instance context
50
  @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
const struct nodeID *const *psample_get_cache(struct psample_context *tc, int *n);
56

    
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
  @param tc the pointer to the current topology manager instance context
69
  @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
const void *psample_get_metadata(struct psample_context *tc, int *metadata_size);
77

    
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
  @param tc the pointer to the current topology manager instance context
84
  @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
int psample_grow_cache(struct psample_context *tc, int n);
88

    
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
  @param tc the pointer to the current topology manager instance context
95
  @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
int psample_shrink_cache(struct psample_context *tc, int n);
99

    
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
  @param tc the pointer to the current topology manager instance context
107
  @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
int psample_remove_peer(struct psample_context *tc, const struct nodeID *neighbour);
112

    
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
  @param tc the pointer to the current topology manager instance context
120
  @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
int psample_change_metadata(struct psample_context *tc, const void *metadata, int metadata_size);
127

    
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
  @param config configuration parameter for the peer sampling module (specifying the
136
         peer sampling algorithm, the cache size, etc...)
137
  @return the topology manager context in case of success; NULL in case of error.
138
*/
139
struct psample_context *psample_init(struct nodeID *myID, const void *metadata, int metadata_size, const char *config);
140

    
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
  @param tc the pointer to the current topology manager instance context
147
  @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
int psample_add_peer(struct psample_context *tc, struct nodeID *neighbour, const void *metadata, int metadata_size);
156

    
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
  @param tc the pointer to the current topology manager instance context
165
  @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
int psample_parse_data(struct psample_context *tc, const uint8_t *buff, int len);
170

    
171
void psample_destroy(struct psample_context **context);
172
#endif /* PEERSAMPLER_H */