Statistics
| Branch: | Revision:

grapes / include / topmanager.h @ 483ff9b6

History | View | Annotate | Download (4.6 KB)

1
#ifndef TOPMAN_H
2
#define TOPMAN_H
3

    
4
/** @file topmanager.h 
5
 *
6
 * @brief Topology Manager interface.
7
 *
8
 * This is the Topology Manager 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 Topology Manager API.
16
 *
17
 */
18

    
19

    
20
/**
21
  @brief Get the peer's neighbourhood.
22

23
  This function returns the current neighbourhood (i.e., the set of
24
  known peers) of a peer, and its size. Note that the current neighbourhood
25
  size can be different from the requested one, because of how the overlay
26
  management protocols work. 
27

28
  @param n pointer to an integer where the neighbourhood size is returned.
29
           Is set to -1 in case of error, or 0 if the neighbourhood is empty.
30
  @return a pointer to an array of nodeID describing the neighbourhood. NULL
31
          in case of error, or if the neighbourhood is empty.
32
*/
33
const struct nodeID **topGetNeighbourhood(int *n);
34

    
35
/**
36
  @brief Get the peer's metadata.
37

38
  Each peer in the neighbourhood can have some opaque metadata attached to
39
  it, and such metadata is gossiped together with the nodeIDs.
40
  This function returns the metadata currently associated to the
41
  neighbours of a peer, and the size of each object composing the metadata
42
  (metadata have the same structure for all the peers, so such size is
43
  constant). The neighbourhood size can be known by calling
44
  topGetNeighbourhood().
45

46
  @param metadata_size pointer to an integer where the size of the metadata
47
         associated to each peer is returned.
48
         Is set to -1 in case of error, or 0 if the neighbourhood is empty.
49
  @return a pointer to an array of metadata (ordered as the peers returned
50
          by topGetNeighbourhood()).
51
          NULL in case of error, or if the neighbourhood is empty.
52
*/
53
const void *topGetMetadata(int *metadata_size);
54

    
55
/**
56
  @brief Increase the neighbourhood size.
57

58
  This function can be used to increase the number of neighbours (that is,
59
       the degree of the overlay graph) by a specified amount.
60
  @param n number of peers by which the neighbourhood size must be incremented.
61
  @return the new neighbourhood size in case of success; -1 in case of error.
62
*/
63
int topGrowNeighbourhood(int n);
64

    
65
/**
66
  @brief Decrease the neighbourhood size.
67

68
  This function can be used to reduce the number of neighbours (that is,
69
       the degree of the overlay graph) by a specified amount.
70
  @param n number of peers by which the neighbourhood size must be decreased.
71
  @return the new neighbourhood size in case of success; -1 in case of error.
72
*/
73
int topShrinkNeighbourhood(int n);
74

    
75
/**
76
  @brief Remove a peer from the neighbourhood.
77

78
  This function can be used to remove a specified neighbour from the
79
  neighbourhood. Note that the requested neighbourhood size is not
80
  modified, so the peer will be soon replaced by a different one.
81
  @param neighbour the id of the peer to be removed from the
82
         neighbourhood.
83
  @return 0 in case of success; -1 in case of error.
84
*/
85
int topRemoveNeighbour(struct nodeID *neighbour);
86

    
87
int topChangeMetadata(void *metadata, int metadata_size);
88

    
89
/**
90
  @brief Initialise the Topology Manager.
91

92
  @param myID the ID of this peer.
93
  @param metadata pointer to the metadata associated to this peer (will be
94
         gossiped).
95
  @param metadata_size size of the metadata associated to this peer.
96
  @return 0 in case of success; -1 in case of error.
97
*/
98
int topInit(struct nodeID *myID, void *metadata, int metadata_size, const char *config);
99

    
100
/**
101
  @brief Insert a peer in the neighbourhood.
102

103
  This function can be used to add a specified neighbour to the
104
  neighbourhood. It is useful in the bootstrap phase.
105
  @param neighbour the id of the peer to be added to the
106
         neighbourhood.
107
  @param metadata pointer to the metadata associated to the new peer (will be
108
         gossiped).
109
  @param metadata_size size of the metadata associated to the new peer (must
110
         be the same as for the other peers).
111
  @return 0 in case of success; -1 in case of error.
112
*/
113
int topAddNeighbour(struct nodeID *neighbour, void *metadata, int metadata_size);
114

    
115
/**
116
  @brief Pass a received packet to the Topology Manager.
117

118
  This function passes to the Topology Manager a packet that has
119
  been received from the network. The Topology Manager will parse
120
  such packet and run the protocol, adding or removing peers to the
121
  neighbourhood, and sending overlay management messages to other peers.
122
  @param buff a memory buffer containing the received message.
123
  @param len the size of such a memory buffer.
124
  @return 0 in case of success; -1 in case of error.
125
*/
126
int topParseData(const uint8_t *buff, int len);
127

    
128
#endif /* TOPMAN_H */