Statistics
| Branch: | Revision:

grapes / include / peersampler.h @ d7aae2f0

History | View | Annotate | Download (5.85 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 an usage example
10
 *
11
 */
12

    
13
/** @example topology_test.c
14
 * 
15
 * A test program showing how to use the Peer Sampler API.
16
 *
17
 */
18

    
19

    
20
/**
21
   @brief Mantains the context of a topology manager instance
22
 */
23
struct psample_context;
24

    
25
/**
26
  @brief Get a sample of the active peers.
27

28
  This function returns the current peer sampler cache (i.e., the set of
29
  known peers), and its size. Note that the current cache 
30
  size can be different from the requested one, because of how the peer 
31
  sampling protocols work. 
32

33
  @param tc the pointer to the current topology manager instance context
34
  @param n pointer to an integer where the cache size is returned.
35
           Is set to -1 in case of error, or 0 if the cache is empty.
36
  @return a pointer to an array of nodeID describing a random view of the system. NULL
37
          in case of error, or if the cache is empty.
38
*/
39
const struct nodeID **psample_get_cache(struct psample_context *tc, int *n);
40

    
41
/**
42
  @brief Get the peer's metadata.
43

44
  Each known peer can have some opaque metadata attached to
45
  it, and such metadata is gossiped together with the nodeIDs.
46
  This function returns the metadata currently associated to the
47
  known peers, and the size of each object composing the metadata
48
  (metadata have the same structure for all the peers, so such size is
49
  constant). The number of known peers (cache size) can be known by calling
50
  psample_get_cache().
51

52
  @param tc the pointer to the current topology manager instance context
53
  @param metadata_size pointer to an integer where the size of the metadata
54
         associated to each peer is returned.
55
         Is set to -1 in case of error, or 0 if the cache is empty.
56
  @return a pointer to an array of metadata (ordered as the peers returned
57
          by psample_get_cache()).
58
          NULL in case of error, or if the cache is empty.
59
*/
60
const void *psample_get_metadata(struct psample_context *tc, int *metadata_size);
61

    
62
/**
63
  @brief Increase the cache size.
64

65
  This function can be used to increase the number of known peers (that is,
66
       the degree of the overlay graph) by a specified amount.
67
  @param tc the pointer to the current topology manager instance context
68
  @param n number of peers by which the cache size must be incremented.
69
  @return the new cache size in case of success; -1 in case of error.
70
*/
71
int psample_grow_cache(struct psample_context *tc, int n);
72

    
73
/**
74
  @brief Decrease the cache size.
75

76
  This function can be used to reduce the number of known peers (that is,
77
       the degree of the overlay graph) by a specified amount.
78
  @param tc the pointer to the current topology manager instance context
79
  @param n number of peers by which the cache size must be decreased.
80
  @return the new cache size in case of success; -1 in case of error.
81
*/
82
int psample_shrink_cache(struct psample_context *tc, int n);
83

    
84
/**
85
  @brief Remove a peer from the cache.
86

87
  This function can be used to remove a specified peer from the
88
  cache. Note that the requested cache size is not
89
  modified, so the peer will be soon replaced by a different one.
90
  @param tc the pointer to the current topology manager instance context
91
  @param neighbour the id of the peer to be removed from the
92
         cache.
93
  @return 0 in case of success; -1 in case of error.
94
*/
95
int psample_remove_peer(struct psample_context *tc, const struct nodeID *neighbour);
96

    
97
/**
98
  @brief Change the metadata.
99

100
  This function can be used to modify/update the metadata for a
101
  peer. Because of security concerns, only the metadata for the
102
  local peer can be modified.
103
  @param tc the pointer to the current topology manager instance context
104
  @param metadata pointer to the new metadata associated to the peer (will be
105
         gossiped).
106
  @param metadata_size size of the metadata associated to the peer (must
107
         be the same as for the other peers).
108
  @return 0 in case of success; -1 in case of error.
109
*/
110
int psample_change_metadata(struct psample_context *tc, const void *metadata, int metadata_size);
111

    
112
/**
113
  @brief Initialise the Peer Sampler.
114

115
  @param myID the ID of this peer.
116
  @param metadata pointer to the metadata associated to this peer (will be
117
         gossiped).
118
  @param metadata_size size of the metadata associated to this peer.
119
  @return the topology manager context in case of success; NULL in case of error.
120
*/
121
struct psample_context *psample_init(struct nodeID *myID, const void *metadata, int metadata_size, const char *config);
122

    
123
/**
124
  @brief Insert a known peer in the cache.
125

126
  This function can be used to add a specified peer to the
127
  cache. It is useful in the bootstrap phase.
128
  @param tc the pointer to the current topology manager instance context
129
  @param neighbour the id of the peer to be added to the
130
         cache.
131
  @param metadata pointer to the metadata associated to the new peer (will be
132
         gossiped).
133
  @param metadata_size size of the metadata associated to the new peer (must
134
         be the same as for the other peers).
135
  @return 0 in case of success; -1 in case of error.
136
*/
137
int psample_add_peer(struct psample_context *tc, struct nodeID *neighbour, const void *metadata, int metadata_size);
138

    
139
/**
140
  @brief Pass a received packet to the Peer Sampler.
141

142
  This function passes to the Peer Sampler a packet that has
143
  been received from the network. The Peer Sampler will parse
144
  such packet and run the protocol, adding or removing peers to the
145
  cache, and sending peer sampling messages to other peers.
146
  @param tc the pointer to the current topology manager instance context
147
  @param buff a memory buffer containing the received message.
148
  @param len the size of such a memory buffer.
149
  @return 0 in case of success; -1 in case of error.
150
*/
151
int psample_parse_data(struct psample_context *tc, const uint8_t *buff, int len);
152

    
153
#endif /* PEERSAMPLER_H */