Revision 6fd9945c include/tman.h

View differences:

include/tman.h
3 3

  
4 4
/** @file tman.h
5 5
 *
6
 * @brief Tman interface.
6
 * @brief Topology Manager interface.
7 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.
8
 * This is the Topology Manager interface.
10 9
 *
11 10
 */
12 11

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

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

  
19 18
  @param target pointer to data that describe the target against which the ranking has to be made.
......
24 23
typedef int (*tmanRankingFunction)(const void *target, const void *p1, const void *p2);
25 24

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

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

  
31 30
  @param myID the ID of this peer.
32 31
  @param metadata Pointer to data associated with the local peer.
33 32
  @param metadata_size Size (number of bytes) of the metadata associated with the local peer.
34
  @param rfun Ranking function to be used to order the peers in tman cache.
35
  @param gossip_peers Number of peers, among those in the cache, to be gossiped in a messaged exchange.
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.
36 35
  @return 0 in case of success; -1 in case of error.
37 36
*/
38
int tmanInit(struct nodeID *myID, void *metadata, int metadata_size, tmanRankingFunction rfun, int gossip_peers); 
37
int tmanInit(struct nodeID *myID, void *metadata, int metadata_size, tmanRankingFunction rfun, const char *config); 
39 38

  
40 39

  
41 40
/**
......
51 50
int tmanAddNeighbour(struct nodeID *neighbour, void *metadata, int metadata_size);
52 51

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

  
56
  This function passes to Tman a packet that has
55
  This function passes to Topology Manager a packet that has
57 56
  been received from the network. The Topology Manager will parse
58 57
  such packet and run the protocol, adding or removing peers to the
59 58
  neighbourhood, and sending overlay management messages to other peers.
60 59
  @param buff a memory buffer containing the received message.
61 60
  @param len the size of such a memory buffer.
62
  @param peers Array of nodeID pointers to be added in tman cache.
61
  @param peers Array of nodeID pointers to be added in Topology Manager cache.
63 62
  @param size Number of elements in peers.
64 63
  @param metadata Pointer to the array of metadata belonging to the peers to be added.
65 64
  @param metadata_size Number of bytes of each metadata.
......
69 68

  
70 69

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

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

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

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

  
96 95
  @return The current size of the neighborhood.
97 96
*/
......
99 98

  
100 99

  
101 100
/**
102
 * @brief Get the highest ranked tman peers.
101
 * @brief Get the best peers.
103 102
 *
104
 * This function allows the user to retrieve the highest ranked n peers from tman cache, along with
103
 * This function allows the user to retrieve the best n peers from Topology Manager cache, along with
105 104
 * their metadata. The number of peers actually returned may be different from what is asked, depending
106 105
 * on the current size of the cache.
107
 * Notice that if the user asks for a number of peers that exceeds the current cache size, a join with
108
 * the known peers set provided via tmanParseData will be triggered at the next
109
 * time tmanParseData is called. This will change (and make unstable,
110
 * at least for few subsequent iterations) the current known topology. Thus, it is advisable to do so only if
111
 * necessary (i.e. when the user really needs more peers to communicate with).
112 106
 *
113
 * @param n The number of peer tman is asked for.
107
 * @param n The number of peer the Topology Manager is asked for.
114 108
 * @param peers Array of nodeID pointers to be filled.
115 109
 * @param metadata Pointer to the array of metadata belonging to the peers to be given.
116 110
 * @return The number of elements in peers.
......
147 141
*/
148 142
int tmanShrinkNeighbourhood(int n);
149 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

  
150 155
#endif /* TMAN_H */
156

  

Also available in: Unified diff