Statistics
| Branch: | Revision:

grapes / include / topmanager.h @ 4d9b08d1

History | View | Annotate | Download (4.53 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

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

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

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

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

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

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

    
127
#endif /* TOPMAN_H */