| << Prev | - Up - | Next >> |
This chapter enumerates and describes the classes and the procedures provided by the P2PS library. The P2PS library has a simple structure. It contains the class P2PServices, procedures to (un)wrap an access point token, and procedures to compute network configuration parameters.
P2PS.p2pServices class The class P2PServices offers different P2P services. Particularly, it provides means to create and to join a P2P network, and communication primitives to exchange messages among nodes. P2PServices objects can be initiated either with method createNet or with method joinNet.
createNet createNet(netConfig:+NetC<= NetConfig
nodeConfig:+NodeC<= NodeConfig
apConfig:+APC<= APConfig
msgStrm:?MS<= _
evntStrm:?ES<= _)
Create a P2P network, i.e., the first node in the network. Configure the P2P network, node, and local node's access point by means of records NetConfig, NodeConfig, and respectively APConfig. Returns the message and the event streams, MS and ES. For more about the message and event streams and their form refer to Chapter 3. Raises exception p2ps(couldNotConfig reason:R comment:C) when there was a problem with the configuration parameters. R is the tuple Param#Val corresponding to the name and value of the parameter that caused the exception. Sometimes, a comment C, as a string, will be added for clarification.
In the following we give the default values of the configuration records NetConfig, NodeConfig and APConfig. One can specify different values for the configuration parameters if need be.
NetConfig
The NetConfig record contains the parameters characterizing the P2P network. Only the Tango protocol is currently supported. Beside the name of the protocol, the corresponding parameters are: the maximum network size, the exponential factor, and the size of the successor list. They should be positive integers. The maximum network size should be greater than the exponential factor. Currently, only odd values greater than 2 are allowed for the exponential factor. See Section 2.3 for the relation between maximum network size, exponential factor, maximum number of hops, and the routing table size.
netConfig(protocol: tango
maxNetSize: 2131
expFactor: 3
succListSize: 10)
NodeConfig
The NodeConfig record contains the parameters characterizing the local P2P node. They are in relation with the network parameters specified with NetConfig. The node Id should be a positive integer, inferior to the maximum network size. If not provided, a random value is chosen. The field at feature useProxy should be false meaning that this node will be an integral part of the P2PS network.
nodeConfig(nodeId: randomly_chosen
useProxy: false)
APConfig
The APConfig record contains the parameters characterizing the local access point (for more about access point, see Section 2.2). Currently, the local access point is characterized by an Ip address and a port number. The Ip should be given as a string, and the port as a positive integer. If Ip is not provided, a map of the host name of the computer to an Ip will be done. The Ip should only be set if the operating system, by some reason, returns a faulty one. If port is not provided, a random one is chosen.
apConfig(ip: localhost
pn: randomly_chosen)
joinNet joinNet(remoteAP:+RemAP
nodeConfig:+NodeC<= NodeConfig
apConfig:+APC<= APConfig
msgStrm:?MS<= _
evntStrm:?ES<= _)
Create a node and join it to the P2P network to which the access point token RemAP is provided (for more about access point, see Section 2.2). Configure the P2P node and the local node's access point by means of records NodeConfig and respectively APConfig. Returns the message and the event streams, MS and ES. For more about the message and event streams and their form refer to Chapter 3. Raises exception p2ps(couldNotConfig reason:R comment:C) when there was a problem with the configuration parameters. R is the tuple Param#Val corresponding to the name and value of the parameter that caused the exception. Sometimes, a comment C, as a string, will be added for clarification. Raises exception p2ps(couldNotJoin) if there was a problem when joining, such as an obsolete token. Raises exception p2ps(nodeAlreadyInNetwork) if this node is already part of a P2PS network. Raises exception p2ps(versionMismatch pversion:PV eversion:EV) if the version of the this package is different than the version of the network. PV is the version of this package and EV is the expected version, i.e., the P2PS version of the nodes in the network to join to.
In the following we give the default values of the configuration records NetConfig, NodeConfig and APConfig. One can specify different values for the configuration parameters if need be.
NodeConfig
The NodeConfig record contains the parameters characterizing the local P2P node. They are in relation with the network parameters. The node Id should be a positive integer inferior to the maximum size of the network to join to. If not provided, a random value is chosen. If the field at feature useProxy is true, then this node will be responsible only for the key corresponding to its Id, and it will interact with the network via a proxy node, i.e., its successor. This functionality is useful when dealing with nodes behind firewalls, or with nodes with limited resources. When useProxy is false, this node will be an integral part of the P2PS network.
nodeConfig(nodeId: randomly_chosen
useProxy: false)
APConfig
The APConfig record contains the parameters characterizing the local access point (for more about access point, see Section 2.2). Currently, the local access point is characterized by an Ip address and a port number. The Ip should be given as a string, and the port as a positive integer. If Ip is not provided, a map of the host name of the computer to an Ip will be done. The Ip should only be set if the operating system, by some reason, returns a faulty one. If a port is not provided, a random one is chosen.
apConfig(ip: localhost
pn: randomly_chosen)
leaveNet leaveNet
Detach this node from the P2PS network. Terminate the message and the event streams (i.e., with nil). After calling leaveNet, a node won't accept messages for sending any more. Trying to send a message will raise exception p2ps(nodeHasLeft).
send send(dst:+NId
msg:+Msg
toResp:+TR<= false)
If TR is false, send message Msg to node with Id NId. Otherwise, if TR is true, NId is considered to be a key, and the message is sent to the key's responsible. The send is asynchronous and does not provide delivery guarantee. Raise exception p2ps(nodeHasLeft) if the node has already left.
rsend rsend(dst:+NId
msg:+Msg
ack:+Ack<= _
context:+C<= nil)
Send Msg to node NId reliably. It is reliable in the sense that all messages sent with rsend from this node to NId will eventually be delivered in a FIFO manner. This will implicitly create a connection between this node and the node NId, and thus generating the event openconn on the event stream. The Ack variable will be bound either to acked as soon as it is known that the message was acknowledged as received, or to nonacked when the connection is closed and there has not been received any acknowledgment for that message. In order to easily recover the non acked messages when the connection is ungracefully closed, a "context" C can be provided with each message to be sent. This context, that can be any Oz entity, will be paired with each non acked message returned by P2PS with the event closeconn. The send is asynchronous but one can synchronize on Ack. Raise exception p2ps(nodeHasLeft) if the node has already left. Note that this method is currently in tests.
multicast multicast(dst:+LNId
msg:+Msg
toResp:+TR<= false)
If TR is false, send message Msg to nodes corresponding to Ids found in list LNId, i.e., explicit multicast. If TR is true, the Ids are considered to be keys, and the message is sent to the keys' responsibles. The send is asynchronous and does not provide delivery guarantee. Raise exception p2ps(nodeHasLeft) if the node has already left.
broadcast broadcast(msg:+Msg
toMyself:+TM<= false)
Send message Msg to all the nodes in the P2PS network including, or not, the source node depending whether TM is set to true or false. Msg can be any Oz value. The send is asynchronous and does not provide delivery guarantee. Raise exception p2ps(nodeHasLeft) if the node has already left.
sendToSucc sendToSucc(msg:+Msg
nrSucc:+N
toMyself:+TM<= false)
Send message Msg to the N successors of this node. Msg can be any Oz value. If this node is part of the successor list and TM==true, send the message to it, too. Raise exception p2ps(nrSuccTooLarge nrSucc:N) if N is greater than the network parameter succListSize (see method createNet). The send is asynchronous and does not provide delivery guarantee. Raise exception p2ps(nodeHasLeft) if the node has already left.
getLocalAP getLocalAP(?AP)
Return the local access point AP of this node (for more about access point, see Section 2.2).
getMsgStrm getMsgStrm(?MS}
Return a stream on which the received messages are available. For more about the message stream and the form of a messages refer to Section 3.1. Note that the messages received before binding MS are not available on the stream. The stream will be ended (with nil) when this node leaves the network.
getEvntStrm getEvntStrm(?ES}
Return a stream on which events occurred in P2PS are available. For more about possible events refer to Section 3.2. Note that the events occurred before binding ES are not available on the stream. The stream will be ended (with nil) when this node leaves the network.
getNetConfig getNetConfig(?NetConfig)
Return the network configuration as a record in the same form as specified in method createNet. The values of the parameters correspond to the current P2P network the node takes part of.
getNodeConfig getNodeConfig(?NodeConfig)
Return the configuration of this node as a record in the same form as specified in methods createNet or joinNet. The values of the parameters are proper to this node.
getAPConfig getAPConfig(?APConfig)
Return the access point configuration of this node as a record in the same form as specified in methods createNet or joinNet. The values of the parameters are proper to this node. For details on access point, see Section 2.2.
getFT getFT(?FT)
Return the current finger table FT of this node. FT has the form of a record with label ft. The record contains the node Ids of the fingers (i.e., the set of neighbors). The maximum number of fingers at a node depends on the maximum network size of the system (see NetConfig). For the positions for which the value of a finger is determined, its node Id is provided, otherwise unit is provided.
getSucc getSucc(?Succ)
Return the Id of the successor of this node. A node alone in the network has itself as successor.
getPred getPred(?Pred)
Return the current Id of the predecessor of this node. A node alone in the network has itself as predecessor.
getSuccList getSuccList(?SuccList)
Return the current successor list of this node. SuccList has the form of a record with label succlist. The record contains the node Ids of the successors of this node. For the maximum number of successors of a node, see NetConfig. The Id of a node may appear in its successor list if the network is smaller than the maximum size of the successor list.
getClients getClients(?Clients)
Return a list with the Ids of the nodes that use this node as proxy.
getStatistics getStatistics(?Stat)
This method provides a set of information, most of it in the form of counters, about the status of the peer node. Stat is a record containing different fields whose meaning is the following. UseProxy is a boolean indicating whether the node uses, or not, a proxy to access to the overlay network. NrDataMsgs_lcl the number of data messages sent by this node. NrDataMsgs_rm the number of data messages forwarded by this node. NrCtrlMsgs_lcl the number of control messages send by this node. NrCtrlMsgs_lcl the number of control messages forwarded by this node. NrAppMsgs the number of messages sent by the application associated with this node. NrFingerChgs the number of times the finger table has changed. NrSuccChgs the number of times the successor has changed. NrPredChgs the number of times the predecessor has changed. NrClients the number of clients this node has. NrOutLinks the number of outgoing links. NrInLinks the number of incoming links.
stat(useProxy:UseProxy
nrDataMsgs_lcl:NrDataMsgs_lcl
nrDataMsgs_rm:NrDataMsgs_rm
nrCtrlMsgs_lcl:NrCtrlMsgs_lcl
nrCtrlMsgs_rm:NrCtrlMsgs_rm
nrAppMsgs:NrAppMsgs
nrFingerChgs:NrFingerChgs
nrSuccChgs:NrSuccChgs
nrPredChgs:NrPredChgs
nrClients:NrClients
nrOutLinks:NrOutLinks
nrInLinks:NrInLinks)
isResponsibleOf isResponsibleOf(key:+Keyresp:?Resp)
Return true if this node is responsible of the key K. Otherwise, return false.
An access point is encoded as a token that carries the access information to a P2PS node and, thus, to a P2PS network. The information it encapsulates is provided by the underlying communication level of P2PS. Currently, this information contains the Ip address of the machine on which the node runs and a port number.
To join a P2PS network, a node has to specify the access point AP of another node already in the network. One can either obtain the corresponding token from another node, or he can build it up with procedure P2PS.address2ap, given the node's Ip address and port#. The opposite procedure is P2PS.ap2address .
address2ap address2ap(+IP+PN?AP)
Given an Ip address IP, as a string, and a port number PN, as an integer, return the corresponding access point token AP.
ap2address ap2address(+AP?IP?PN)
Given an access point AP, return the Ip address IP, as a string, and the port number PN, as an integer. Raise exception p2ps(wrongAPFormat ap:AP) if AP is has a wrong format
One can be interested in computing the configuration parameters of her network by specifying some constraints. Then, a list of possible parameters can be provided from which one can choose the most suitable one. The procedure P2PS.computeParams can be used to compute the parameters for a Tango network.
computeParams computeParams(+NetParams)
In Tango there is a strong relation between the maximum size of the network, the maximum number of hops to reach every node in the network, the size of the routing table at each node, and the exponential factor of the network. This method, computes all the possible combinations with respect to the given network parameters. NetParams is a record which must contain at least the field minNetSize corresponding to the minimum desired network size. The other constraints can be maxHops, maxRTSize and maxExpFactor, that is the maximum number of hops, the maximum size of the routing table and respectively the maximum exponential factor. Return a list of records of the form param(expFactor:EF maxHops:MH maxNetSize:MS rtSize:RTS), where EF is the exponential factor, MH is the maximum number of hops, MS is the maximum network size, and RTS is the size of the routing table. The list can be empty if there is no solution found for the provided parameters.
For example,
{P2PS.computeParams r(minNetSize:200)}yields the following as output:
[param(expFactor:199 maxHops:1 maxNetSize:200 rtSize:199)
param(expFactor:15 maxHops:2 maxNetSize:239 rtSize:30)
param(expFactor:7 maxHops:3 maxNetSize:433 rtSize:21)
param(expFactor:5 maxHops:4 maxNetSize:985 rtSize:20)
param(expFactor:3 maxHops:5 maxNetSize:571 rtSize:15)] Whereas, if we add more constraints, such as the maximum size of the routing table maxRTSize, we can reduce the resulted domain.
{P2PS.computeParams r(minNetSize:200 maxRTSize:16)}yields the following as output:
[param(expFactor:3 maxHops:5 maxNetSize:571 rtSize:15)]
version version
A parameter bound to a value representing the version of the current P2PS package. The value is a string of the following form: "P2PS version YYYYMMDD".
| << Prev | - Up - | Next >> |