Statistics
| Branch: | Revision:

grapes / include / tman.h @ df98cd3a

History | View | Annotate | Download (8.21 KB)

1
#ifndef TMAN_H
2
#define TMAN_H
3

    
4
/** @file tman.h
5
 *
6
 * @brief Tman interface.
7
 *
8
 * This is the Tman interface. Tman builds a given topology according to a user provided ranking
9
 * algorithm, by means of epidemic-style message exchanges with neighbor peers.
10
 *
11
 */
12

    
13
/**
14
  @brief Compare neighbors features.
15

16
  The functions implementing this prototype are used to compare neighbors features against a given
17
  target neighbor, in order to obtain a rank, to be used to build a given topology.
18

19
  @param target pointer to data that describe the target against which the ranking has to be made.
20
  @param p1 pointer to data that describe the first neighbor.
21
  @param p2 pointer to data that describe the second neighbor.
22
  @return 1 if p1 is to be ranked first; 2 if p2 is to be ranked first; 0 if there is a tie.
23
*/
24
typedef int (*tmanRankingFunction)(const void *target, const void *p1, const void *p2);
25

    
26
/*
27
  @brief Get the peer's neighbourhood.
28

29
  This function returns the current neighbourhood (i.e., the set of
30
  known peers) of a peer, and its size. Note that the current neighbourhood
31
  size can be different from the requested one, because of how the overlay
32
  management protocols work. 
33

34
  @param n pointer to an integer where the neighbourhood size is returned.
35
           Is set to -1 in case of error, or 0 if the neighbourhood is empty.
36
  @return a pointer to an array of nodeID describing the neighbourhood. NULL
37
          in case of error, or if the neighbourhood is empty.
38
*/
39
//const struct nodeID **tmanGetNeighbourhood(int *n);
40

    
41
/*
42
  @brief Remove a peer from the neighbourhood.
43

44
  This function can be used to remove a specified neighbour from the
45
  neighbourhood. Note that the requested neighbourhood size is not
46
  modified, so the peer will be soon replaced by a different one.
47
  @param neighbour the id of the peer to be removed from the neighbourhood.
48
  @return 0 in case of success; -1 in case of error.
49
*/
50
//int tmanRemoveNeighbour(struct nodeID *neighbour);
51

    
52
/**
53
  @brief Initialise Tman.
54

55
  This function initializes tman protocol with all the mandatory parameters.
56

57
  @param myID the ID of this peer.
58
  @param metadata Pointer to data associated with the local peer.
59
  @param metadata_size Size (number of bytes) of the metadata associated with the local peer.
60
  @param rfun Ranking function to be used to order the peers in tman cache.
61
  @param gossip_peers Number of peers, among those in the cache, to be gossiped in a messaged exchange.
62
  @return 0 in case of success; -1 in case of error.
63
*/
64
int tmanInit(struct nodeID *myID, void *metadata, int metadata_size, tmanRankingFunction rfun, int gossip_peers); 
65
//, int max_peers, int max_idle, int periodicity
66

    
67
/*
68
  @brief Start Tman.
69

70
  This function starts Tman by feeding it with fresh peers from some known source (usually a
71
  peer sampling service, giving a random sample of the network).
72

73
  @param peers Array of nodeID pointers to be added in tman cache.
74
  @param size Number of elements in peers.
75
  @param metadata Pointer to the array of metadata belonging to the peers to be added.
76
  @param metadata_size Number of bytes of each metadata.
77
  @param rfun Ranking function to be used to order the peers in tman cache.
78
  @param best_peers
79
  @param gossip_peers
80
  @return 0 in case of success; -1 in case of error.
81
*/
82
//int tmanStart(const struct nodeID **peers, int size, const void *metadata, int metadata_size);
83

    
84

    
85
/**
86
  @brief Insert a peer in the neighbourhood.
87

88
  This function can be used to add a specified neighbour to the
89
  neighbourhood.
90
  @param neighbour the id of the peer to be added to the neighbourhood.
91
  @param metadata Pointer to the array of metadata belonging to the peers to be added.
92
  @param metadata_size Number of bytes of each metadata.
93
  @return 0 in case of success; -1 in case of error.
94
*/
95
int tmanAddNeighbour(struct nodeID *neighbour, void *metadata, int metadata_size);
96

    
97
/**
98
  @brief Pass a received packet to Tman.
99

100
  This function passes to Tman a packet that has
101
  been received from the network. The Topology Manager will parse
102
  such packet and run the protocol, adding or removing peers to the
103
  neighbourhood, and sending overlay management messages to other peers.
104
  @param buff a memory buffer containing the received message.
105
  @param len the size of such a memory buffer.
106
  @param peers Array of nodeID pointers to be added in tman cache.
107
  @param size Number of elements in peers.
108
  @param metadata Pointer to the array of metadata belonging to the peers to be added.
109
  @param metadata_size Number of bytes of each metadata.
110
  @return 0 in case of success; -1 in case of error.
111
*/
112
int tmanParseData(const uint8_t *buff, int len, const struct nodeID **peers, int size, const void *metadata, int metadata_size);
113

    
114

    
115
/**
116
  @brief Change the metadata in tman neighborhood.
117

118
  This function changes the metadata associated with the current node.
119

120
  @param metadata Pointer to the metadata belonging to the peer.
121
  @param metadata_size Number of bytes of the metadata.
122
  @return 1 if successful, -1 otherwise.
123
 */
124
int tmanChangeMetadata(void *metadata, int metadata_size);
125

    
126
/**
127
  @brief Get the metadata of the neighbors.
128
  @param metadata_size Address of the integer that will be set to the size of each metadata.
129
  @return a pointer to the array of metadata associated with the peers in the neighbourhood. NULL
130
          in case of error, or if the neighbourhood is empty.
131
*/
132
const void *tmanGetMetadata(int *metadata_size);
133

    
134

    
135
/**
136
  @brief Get the current neighborhood size.
137

138
  This function returns the current number of peers in the local tman neighborhood.
139

140
  @return The current size of the neighborhood.
141
*/
142
const int tmanGetNeighbourhoodSize();
143

    
144
/*
145
        @brief Get the state of Tman.
146

147
        This function tells whether Tman is active or idle.
148

149
        @return 1 if Tman is active, 0 if it is idle.
150
*/
151
//const int tmanGetState();
152

    
153

    
154
//int tmanSetRankingFunction(tmanRankingFunction f);
155

    
156

    
157
//int tmanSetBestPeers(int p);
158

    
159

    
160
//int tmanSetPeriod(int p);
161

    
162
/**
163
 * @brief Get the highest ranked tman peers.
164
 *
165
 * This function allows the user to retrieve the highest ranked n peers from tman cache, along with
166
 * their metadata. The number of peers actually returned may be different from what is asked, depending
167
 * on the current size of the cache.
168
 * Notice that if the user asks for a number of peers that exceeds the current cache size, a join with
169
 * the known peers set provided via tmanParseData will be triggered at the next
170
 * time tmanParseData is called. This will change (and make unstable,
171
 * at least for few subsequent iterations) the current known topology. Thus, it is advisable to do so only if
172
 * necessary (i.e. when the user really needs more peers to communicate with).
173
 *
174
 * @param n The number of peer tman is asked for.
175
 * @param peers Array of nodeID pointers to be filled.
176
 * @param metadata Pointer to the array of metadata belonging to the peers to be given.
177
 * @return The number of elements in peers.
178
 */
179
int tmanGivePeers (int n, struct nodeID **peers, void *metadata);//, int *metadata_size);
180

    
181

    
182
/**
183
  @brief Increase the neighbourhood size.
184

185
  This function can be used to increase the number of neighbours (that is,
186
       the degree of the overlay graph) by a specified amount.
187
       The actual size change will be done the next time tmanParseData is called.
188
       As currently implemented, it doubles the current size at most.
189
       If the argument is negative or a resize has already been requested, but not performed yet,
190
       no change will occur and an error code is returned.
191
  @param n number of peers by which the neighbourhood size must be incremented.
192
  @return the new neighbourhood size in case of success; -1 in case of error.
193
*/
194
int tmanGrowNeighbourhood(int n);
195

    
196

    
197
/**
198
  @brief Decrease the neighbourhood size.
199

200
  This function can be used to reduce the number of neighbours (that is,
201
       the degree of the overlay graph) by a specified amount.
202
       The actual size change will be done the next time tmanParseData is called.
203
       If the argument is negative, or greater equal than the current cache size,
204
        or a resize has already been requested, but not performed yet,
205
       no change will occur and an error code is returned.
206
  @param n number of peers by which the neighbourhood size must be decreased.
207
  @return the new neighbourhood size in case of success; -1 in case of error.
208
*/
209
int tmanShrinkNeighbourhood(int n);
210

    
211
#endif /* TMAN_H */