grapes / include / tman.h @ master
History | View | Annotate | Download (5.93 KB)
1 | df98cd3a | Luca Abeni | #ifndef TMAN_H
|
---|---|---|---|
2 | #define TMAN_H
|
||
3 | |||
4 | /** @file tman.h
|
||
5 | *
|
||
6 | 6fd9945c | Marco Biazzini | * @brief Topology Manager interface.
|
7 | df98cd3a | Luca Abeni | *
|
8 | 6fd9945c | Marco Biazzini | * This is the Topology Manager interface.
|
9 | df98cd3a | Luca Abeni | *
|
10 | */
|
||
11 | |||
12 | /**
|
||
13 | @brief Compare neighbors features.
|
||
14 | |||
15 | 6fd9945c | Marco Biazzini | The functions implementing this prototype may be used to compare neighbors features against a given
|
16 | df98cd3a | Luca Abeni | 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 | 6fd9945c | Marco Biazzini | @brief Initialise the Topology Manager.
|
27 | df98cd3a | Luca Abeni | |
28 | 6fd9945c | Marco Biazzini | This function initializes the Topology Manager protocol with all the mandatory parameters.
|
29 | df98cd3a | Luca Abeni | |
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 | 6fd9945c | Marco Biazzini | @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 | df98cd3a | Luca Abeni | @return 0 in case of success; -1 in case of error.
|
36 | */
|
||
37 | 6fd9945c | Marco Biazzini | int tmanInit(struct nodeID *myID, void *metadata, int metadata_size, tmanRankingFunction rfun, const char *config); |
38 | df98cd3a | Luca Abeni | |
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 | 6fd9945c | Marco Biazzini | @brief Pass a received packet to Topology Manager.
|
54 | df98cd3a | Luca Abeni | |
55 | 6fd9945c | Marco Biazzini | This function passes to Topology Manager a packet that has
|
56 | df98cd3a | Luca Abeni | 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 | 6fd9945c | Marco Biazzini | @param peers Array of nodeID pointers to be added in Topology Manager cache.
|
62 | df98cd3a | Luca Abeni | @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 | d74d9d89 | Luca Abeni | int tmanParseData(const uint8_t *buff, int len, struct nodeID **peers, int size, const void *metadata, int metadata_size); |
68 | df98cd3a | Luca Abeni | |
69 | |||
70 | /**
|
||
71 | 6fd9945c | Marco Biazzini | @brief Change the metadata in Topology Manager neighborhood.
|
72 | df98cd3a | Luca Abeni | |
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 | 483ff9b6 | Marco Biazzini | int tmanChangeMetadata(void *metadata, int metadata_size); |
80 | df98cd3a | Luca Abeni | |
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 | 6fd9945c | Marco Biazzini | This function returns the current number of peers in the local Topology Manager neighborhood.
|
94 | df98cd3a | Luca Abeni | |
95 | @return The current size of the neighborhood.
|
||
96 | */
|
||
97 | bb14413e | Luca Abeni | int tmanGetNeighbourhoodSize(void); |
98 | df98cd3a | Luca Abeni | |
99 | |||
100 | /**
|
||
101 | 6fd9945c | Marco Biazzini | * @brief Get the best peers.
|
102 | df98cd3a | Luca Abeni | *
|
103 | 6fd9945c | Marco Biazzini | * This function allows the user to retrieve the best n peers from Topology Manager cache, along with
|
104 | df98cd3a | Luca Abeni | * 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 | 6fd9945c | Marco Biazzini | * @param n The number of peer the Topology Manager is asked for.
|
108 | df98cd3a | Luca Abeni | * @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 | e8496f96 | MarcoBiazzini | int tmanGivePeers (int n, struct nodeID **peers, void *metadata); |
113 | df98cd3a | Luca Abeni | |
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 | 6fd9945c | Marco Biazzini | |
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 | df98cd3a | Luca Abeni | #endif /* TMAN_H */ |