topmanager.h File Reference

Topology Manager interface. More...

Go to the source code of this file.

Functions
struct nodeID **	topGetNeighbourhood (int *n)
	Get the peer's neighbourhood.
const void *	topGetMetadata (int *metadata_size)
	Get the peer's metadata.
int	topGrowNeighbourhood (int n)
	Increase the neighbourhood size.
int	topShrinkNeighbourhood (int n)
	Decrease the neighbourhood size.
int	topRemoveNeighbour (struct nodeID *neighbour)
	Remove a peer from the neighbourhood.
int	topChangeMetadata (struct nodeID *peer, void *metadata, int metadata_size)
	Change the metadata.
int	topInit (struct nodeID *myID, void *metadata, int metadata_size, const char *config)
	Initialise the Topology Manager.
int	topAddNeighbour (struct nodeID *neighbour, void *metadata, int metadata_size)
	Insert a peer in the neighbourhood.
int	topParseData (const uint8_t *buff, int len)
	Pass a received packet to the Topology Manager.

---

Detailed Description

Topology Manager interface.

This is the Topology Manager interface. See topology_test.c for an usage example

---

Function Documentation

int topAddNeighbour	(	struct nodeID *	neighbour,
		void *	metadata,
		int	metadata_size
	)

Insert a peer in the neighbourhood.

This function can be used to add a specified neighbour to the neighbourhood. It is useful in the bootstrap phase.

Parameters:

	neighbour	the id of the peer to be added to the neighbourhood.
	metadata	pointer to the metadata associated to the new peer (will be gossiped).
	metadata_size	size of the metadata associated to the new peer (must be the same as for the other peers).

Returns:

0 in case of success; -1 in case of error.

Examples:

topology_test.c.

int topChangeMetadata	(	struct nodeID *	peer,
		void *	metadata,
		int	metadata_size
	)

Change the metadata.

This function can be used to modify/update the metadata for a peer. Because of security concerns, only the metadata for the local peer can be modified.

Parameters:

	peer	the id of the peer for which the metadata should be updated (only the local peer is acceptable).
	metadata	pointer to the new metadata associated to the peer (will be gossiped).
	metadata_size	size of the metadata associated to the peer (must be the same as for the other peers).

Returns:

0 in case of success; -1 in case of error.

const void* topGetMetadata

(

int *

metadata_size

)

Get the peer's metadata.

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

Parameters:

metadata_size

pointer to an integer where the size of the metadata associated to each peer is returned. Is set to -1 in case of error, or 0 if the neighbourhood is empty.

Returns:

a pointer to an array of metadata (ordered as the peers returned by topGetNeighbourhood()). NULL in case of error, or if the neighbourhood is empty.

struct nodeID** topGetNeighbourhood

(

int *

n

)

[read]

Get the peer's neighbourhood.

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

Parameters:

n

pointer to an integer where the neighbourhood size is returned. Is set to -1 in case of error, or 0 if the neighbourhood is empty.

Returns:

a pointer to an array of nodeID describing the neighbourhood. NULL in case of error, or if the neighbourhood is empty.

Examples:

topology_test.c.

int topGrowNeighbourhood

(

int

n

)

Increase the neighbourhood size.

This function can be used to increase the number of neighbours (that is, the degree of the overlay graph) by a specified amount.

Parameters:

n

number of peers by which the neighbourhood size must be incremented.

Returns:

the new neighbourhood size in case of success; -1 in case of error.

int topInit	(	struct nodeID *	myID,
		void *	metadata,
		int	metadata_size,
		const char *	config
	)

Initialise the Topology Manager.

Parameters:

	myID	the ID of this peer.
	metadata	pointer to the metadata associated to this peer (will be gossiped).
	metadata_size	size of the metadata associated to this peer.

Returns:

0 in case of success; -1 in case of error.

Examples:

topology_test.c.

int topParseData	(	const uint8_t *	buff,
		int	len
	)

Pass a received packet to the Topology Manager.

This function passes to the Topology Manager a packet that has been received from the network. The Topology Manager will parse such packet and run the protocol, adding or removing peers to the neighbourhood, and sending overlay management messages to other peers.

Parameters:

	buff	a memory buffer containing the received message.
	len	the size of such a memory buffer.

Returns:

0 in case of success; -1 in case of error.

Examples:

topology_test.c.

int topRemoveNeighbour

(

struct nodeID *

neighbour

)

Remove a peer from the neighbourhood.

This function can be used to remove a specified neighbour from the neighbourhood. Note that the requested neighbourhood size is not modified, so the peer will be soon replaced by a different one.

Parameters:

neighbour

the id of the peer to be removed from the neighbourhood.

Returns:

0 in case of success; -1 in case of error.

int topShrinkNeighbourhood

(

int

n

)

Decrease the neighbourhood size.

This function can be used to reduce the number of neighbours (that is, the degree of the overlay graph) by a specified amount.

Parameters:

n

number of peers by which the neighbourhood size must be decreased.

Returns:

the new neighbourhood size in case of success; -1 in case of error.