Statistics
| Branch: | Revision:

grapes / include / tman.h @ b79c8e3a

History | View | Annotate | Download (5.93 KB)

1
#ifndef TMAN_H
2
#define TMAN_H
3

    
4
/** @file tman.h
5
 *
6
 * @brief Topology Manager interface.
7
 *
8
 * This is the Topology Manager interface.
9
 *
10
 */
11

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

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

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

    
25
/**
26
  @brief Initialise the Topology Manager.
27

28
  This function initializes the Topology Manager protocol with all the mandatory parameters.
29

30
  @param myID the ID of this peer.
31
  @param metadata Pointer to data associated with the local peer.
32
  @param metadata_size Size (number of bytes) of the metadata associated with the local peer.
33
  @param rfun Ranking function that may be used to order the peers in tman cache.
34
  @param config Pointer to a configuration file that contains all relevant initialization data.
35
  @return 0 in case of success; -1 in case of error.
36
*/
37
int tmanInit(struct nodeID *myID, void *metadata, int metadata_size, tmanRankingFunction rfun, const char *config); 
38

    
39

    
40
/**
41
  @brief Insert a peer in the neighbourhood.
42

43
  This function can be used to add a specified neighbour to the
44
  neighbourhood.
45
  @param neighbour the id of the peer to be added to the neighbourhood.
46
  @param metadata Pointer to the array of metadata belonging to the peers to be added.
47
  @param metadata_size Number of bytes of each metadata.
48
  @return 0 in case of success; -1 in case of error.
49
*/
50
int tmanAddNeighbour(struct nodeID *neighbour, void *metadata, int metadata_size);
51

    
52
/**
53
  @brief Pass a received packet to Topology Manager.
54

55
  This function passes to Topology Manager a packet that has
56
  been received from the network. The Topology Manager will parse
57
  such packet and run the protocol, adding or removing peers to the
58
  neighbourhood, and sending overlay management messages to other peers.
59
  @param buff a memory buffer containing the received message.
60
  @param len the size of such a memory buffer.
61
  @param peers Array of nodeID pointers to be added in Topology Manager cache.
62
  @param size Number of elements in peers.
63
  @param metadata Pointer to the array of metadata belonging to the peers to be added.
64
  @param metadata_size Number of bytes of each metadata.
65
  @return 0 in case of success; -1 in case of error.
66
*/
67
int tmanParseData(const uint8_t *buff, int len, struct nodeID **peers, int size, const void *metadata, int metadata_size);
68

    
69

    
70
/**
71
  @brief Change the metadata in Topology Manager neighborhood.
72

73
  This function changes the metadata associated with the current node.
74

75
  @param metadata Pointer to the metadata belonging to the peer.
76
  @param metadata_size Number of bytes of the metadata.
77
  @return 1 if successful, -1 otherwise.
78
 */
79
int tmanChangeMetadata(void *metadata, int metadata_size);
80

    
81
/**
82
  @brief Get the metadata of the neighbors.
83
  @param metadata_size Address of the integer that will be set to the size of each metadata.
84
  @return a pointer to the array of metadata associated with the peers in the neighbourhood. NULL
85
          in case of error, or if the neighbourhood is empty.
86
*/
87
const void *tmanGetMetadata(int *metadata_size);
88

    
89

    
90
/**
91
  @brief Get the current neighborhood size.
92

93
  This function returns the current number of peers in the local Topology Manager neighborhood.
94

95
  @return The current size of the neighborhood.
96
*/
97
int tmanGetNeighbourhoodSize(void);
98

    
99

    
100
/**
101
 * @brief Get the best peers.
102
 *
103
 * This function allows the user to retrieve the best n peers from Topology Manager cache, along with
104
 * their metadata. The number of peers actually returned may be different from what is asked, depending
105
 * on the current size of the cache.
106
 *
107
 * @param n The number of peer the Topology Manager is asked for.
108
 * @param peers Array of nodeID pointers to be filled.
109
 * @param metadata Pointer to the array of metadata belonging to the peers to be given.
110
 * @return The number of elements in peers.
111
 */
112
int tmanGivePeers (int n, struct nodeID **peers, void *metadata);
113

    
114

    
115
/**
116
  @brief Increase the neighbourhood size.
117

118
  This function can be used to increase the number of neighbours (that is,
119
       the degree of the overlay graph) by a specified amount.
120
       The actual size change will be done the next time tmanParseData is called.
121
       As currently implemented, it doubles the current size at most.
122
       If the argument is negative or a resize has already been requested, but not performed yet,
123
       no change will occur and an error code is returned.
124
  @param n number of peers by which the neighbourhood size must be incremented.
125
  @return the new neighbourhood size in case of success; -1 in case of error.
126
*/
127
int tmanGrowNeighbourhood(int n);
128

    
129

    
130
/**
131
  @brief Decrease the neighbourhood size.
132

133
  This function can be used to reduce the number of neighbours (that is,
134
       the degree of the overlay graph) by a specified amount.
135
       The actual size change will be done the next time tmanParseData is called.
136
       If the argument is negative, or greater equal than the current cache size,
137
        or a resize has already been requested, but not performed yet,
138
       no change will occur and an error code is returned.
139
  @param n number of peers by which the neighbourhood size must be decreased.
140
  @return the new neighbourhood size in case of success; -1 in case of error.
141
*/
142
int tmanShrinkNeighbourhood(int n);
143

    
144

    
145
/**
146
 * @brief Remove a neighbour.
147

148
  Delete a neighbour from the Topology Manager neighborhood.
149

150
  @param neighbour Pointer to the nodeID of the neighbor to be removed.
151
  @return 1 if removal was successful, -1 if it was not.
152
 */
153
int tmanRemoveNeighbour(struct nodeID *neighbour);
154

    
155
#endif /* TMAN_H */
156