pyndn.sync package

Submodules

pyndn.sync.chrono_sync2013 module

This module defines the ChronoSync2013 class which implements the NDN ChronoSync protocol as described in the 2013 paper “Let’s ChronoSync: Decentralized Dataset State Synchronization in Named Data Networking”. http://named-data.net/publications/chronosync . Note: The support for ChronoSync is experimental and the API is not finalized. See the API docs for more detail at http://named-data.net/doc/ndn-ccl-api/chrono-sync2013.html .

class pyndn.sync.chrono_sync2013.ChronoSync2013(onReceivedSyncState, onInitialized, applicationDataPrefix, applicationBroadcastPrefix, sessionNo, face, keyChain, certificateName, syncLifetime, onRegisterFailed)

Bases: object

Create a new ChronoSync2013 to communicate using the given face. Initialize the digest log with a digest of “00” and and empty content. Register the applicationBroadcastPrefix to receive interests for sync state messages and express an interest for the initial root digest “00”. Note: Your application must call processEvents. Since processEvents modifies the internal ChronoSync data structures, your application should make sure that it calls processEvents in the same thread as this constructor (which also modifies the data structures).

Parameters:

• onReceivedSyncState (function object) – When ChronoSync receives a sync state message, this calls onReceivedSyncState(syncStates, isRecovery) where syncStates is the list of SyncState messages and isRecovery is true if this is the initial list of SyncState messages or from a recovery interest. (For example, if isRecovery is true, a chat application would not want to re-display all the associated chat messages.) The callback should send interests to fetch the application data for the sequence numbers in the sync state. NOTE: The library will log any exceptions raised by this callback, but for better error handling the callback should catch and properly handle any exceptions.
• onInitialized (function object) – This calls onInitialized() when the first sync data is received (or the interest times out because there are no other publishers yet). NOTE: The library will log any exceptions raised by this callback, but for better error handling the callback should catch and properly handle any exceptions.
• applicationDataPrefix (Name) – The prefix used by this application instance for application data. For example, “/my/local/prefix/ndnchat4/0K4wChff2v”. This is used when sending a sync message for a new sequence number. In the sync message, this uses applicationDataPrefix.toUri().
• applicationBroadcastPrefix (Name) – The broadcast name prefix including the application name. For example, “/ndn/broadcast/ChronoChat-0.3/ndnchat1”. This makes a copy of the name.
• sessionNo (int) – The session number used with the applicationDataPrefix in sync state messages.
• face (Face) – The Face for calling registerPrefix and expressInterest. The Face object must remain valid for the life of this ChronoSync2013 object.
• keyChain (KeyChain) – To sign a data packet containing a sync state message, this calls keyChain.sign(data, certificateName).
• certificateName (Name) – The certificate name of the key to use for signing a data packet containing a sync state message.
• syncLifetime (float) – The interest lifetime in milliseconds for sending sync interests.
• onRegisterFailed (function object) – If failed to register the prefix to receive interests for the applicationBroadcastPrefix, this calls onRegisterFailed(applicationBroadcastPrefix). NOTE: The library will log any exceptions raised by this callback, but for better error handling the callback should catch and properly handle any exceptions.

class SyncState(dataPrefixUri, sessionNo, sequenceNo)

Bases: object

A SyncState holds the values of a sync state message which is passed to the onReceivedSyncState callback which was given to the ChronoSyn2013 constructor. Note: this has the same info as the Protobuf class sync_state_pb2.SyncState, but we make a separate class so that we don’t need the Protobuf definition in the ChronoSync API.

getDataPrefix()

Get the application data prefix for this sync state message.

Returns:The application data prefix as a Name URI string. Return type:str

getSequenceNo()

Get the sequence number for this sync state message.

Returns:The sequence number. Return type:int

getSessionNo()

Get the session number associated with the application data prefix for this sync state message.

Returns:The session number. Return type:int

ChronoSync2013.getProducerSequenceNo(dataPrefix, sessionNo)

Get the current sequence number in the digest tree for the given producer dataPrefix and sessionNo.

Parameters:

• dataPrefix (std) – The producer data prefix as a Name URI string.
• sessionNo (int) – The producer session number.

Returns:

The current producer sequence number, or -1 if the producer namePrefix and sessionNo are not in the digest tree.

Return type:

int

ChronoSync2013.getSequenceNo()

Get the sequence number of the latest data published by this application instance.

Returns:The sequence number. Return type:int

ChronoSync2013.publishNextSequenceNo()

Increment the sequence number, create a sync message with the new sequence number and publish a data packet where the name is the applicationBroadcastPrefix + the root digest of the current digest tree. Then add the sync message to the digest tree and digest log which creates a new root digest. Finally, express an interest for the next sync update with the name applicationBroadcastPrefix + the new root digest. After this, your application should publish the content for the new sequence number. You can get the new sequence number with getSequenceNo(). Note: Your application must call processEvents. Since processEvents modifies the internal ChronoSync data structures, your application should make sure that it calls processEvents in the same thread as publishNextSequenceNo() (which also modifies the data structures).

ChronoSync2013.shutdown()

Unregister callbacks so that this does not respond to interests anymore. If you will discard this ChronoSync2013 object while your application is still running, you should call shutdown() first. After calling this, you should not call publishNextSequenceNo() again since the behavior will be undefined. Note: Because this modifies internal ChronoSync data structures, your application should make sure that it calls processEvents in the same thread as shutdown() (which also modifies the data structures).

pyndn.sync.digest_tree module

This module defines the DigestTree class which maintains a digest tree for ChronoSync.

class pyndn.sync.digest_tree.DigestTree

Bases: object

class Node(dataPrefix, sessionNo, sequenceNo)

Bases: object

Create a new DigestTree.Node with the given fields and compute the digest.

Parameters:

• dataPrefix (str) – The data prefix. In Python3, this is encoded as UTF-8 to digest.
• sessionNo (int) – The session number.
• sequenceNo (int) – The sequence number.

getDataPrefix()

Get the data prefix.

Returns:The data prefix. Return type:str

getDigest()

Get the digest.

Returns:The digest as a hex string. Return type:str

getSequenceNo()

Get the sequence number.

Returns:The sequence number. Return type:int

getSessionNo()

Get the session number.

Returns:The session number. Return type:int

lessThan(node2)

Compare this Node with node2 first comparing _dataPrefix then _sessionNo.

Parameters:node2 (DigestTree.Node) – The other Node to compare. Returns:True if this node is less than node2. Return type:bool

setSequenceNo(sequenceNo)

Set the sequence number and recompute the digest.

Parameters:sequenceNo (int) – The new sequence number.

DigestTree.find(dataPrefix, sessionNo)

DigestTree.get(i)

DigestTree.getRoot()

Get the root digest.

Returns:The root digest as a hex string. Return type:str

DigestTree.size()

DigestTree.update(dataPrefix, sessionNo, sequenceNo)

Update the digest tree and recompute the root digest. If the combination of dataPrefix and sessionNo already exists in the tree then update its sequenceNo (only if the given sequenceNo is newer), otherwise add a new node.

Parameters:

• dataPrefix (str) – The data prefix. In Python3, this is encoded as UTF-8 to digest.
• sequenceNo (int) – The sequence number.
• sessionNo (int) – The session number.

Returns:

True if the digest tree is updated, False if not (because the given sequenceNo is not newer than the existing sequence number).

Return type:

bool

pyndn.sync.sync_state_pb2 module

class pyndn.sync.sync_state_pb2.SyncState(**kwargs)

Bases: google.protobuf.message.Message

ActionType = <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x6e007d0>

ByteSize()

Clear()

ClearField(field_name)

DELETE = 1

DESCRIPTOR = <google.protobuf.descriptor.Descriptor object at 0x6e003d0>

FindInitializationErrors()

Finds required fields which are not initialized.

Returns:

A list of strings. Each string is a path to an uninitialized field from the top-level message, e.g. “foo.bar[5].baz”.

static FromString(s)

HasField(field_name)

IsInitialized(errors=None)

Checks if all required fields of a message are set.

Args:

errors: A list which, if provided, will be populated with the field

paths of all missing required fields.

Returns:

True iff the specified message has all required fields set.

ListFields()

MergeFrom(msg)

MergeFromString(serialized)

NAME_FIELD_NUMBER = 1

OTHER = 2

static RegisterExtension(extension_handle)

SEQNO_FIELD_NUMBER = 3

class SeqNo(**kwargs)

Bases: google.protobuf.message.Message

ByteSize()

Clear()

ClearField(field_name)

DESCRIPTOR = <google.protobuf.descriptor.Descriptor object at 0x6e002d0>

FindInitializationErrors()

Finds required fields which are not initialized.

Returns:

A list of strings. Each string is a path to an uninitialized field from the top-level message, e.g. “foo.bar[5].baz”.

static FromString(s)

HasField(field_name)

IsInitialized(errors=None)

Checks if all required fields of a message are set.

Args:

errors: A list which, if provided, will be populated with the field

paths of all missing required fields.

Returns:

True iff the specified message has all required fields set.

ListFields()

MergeFrom(msg)

MergeFromString(serialized)

static RegisterExtension(extension_handle)

SEQ_FIELD_NUMBER = 1

SESSION_FIELD_NUMBER = 2

SerializePartialToString()

SerializeToString()

SetInParent()

Sets the _cached_byte_size_dirty bit to true, and propagates this to our listener iff this was a state change.

WhichOneof(oneof_name)

Returns the name of the currently set field inside a oneof, or None.

seq

Magic attribute generated for “seq” proto field.

session

Magic attribute generated for “session” proto field.

SyncState.SerializePartialToString()

SyncState.SerializeToString()

SyncState.SetInParent()

Sets the _cached_byte_size_dirty bit to true, and propagates this to our listener iff this was a state change.

SyncState.TYPE_FIELD_NUMBER = 2

SyncState.UPDATE = 0

SyncState.WhichOneof(oneof_name)

Returns the name of the currently set field inside a oneof, or None.

SyncState.name

Magic attribute generated for “name” proto field.

SyncState.seqno

Magic attribute generated for “seqno” proto field.

SyncState.type

Magic attribute generated for “type” proto field.

class pyndn.sync.sync_state_pb2.SyncStateMsg(**kwargs)

Bases: google.protobuf.message.Message

ByteSize()

Clear()

ClearField(field_name)

DESCRIPTOR = <google.protobuf.descriptor.Descriptor object at 0x6e00450>

FindInitializationErrors()

Finds required fields which are not initialized.

Returns:

A list of strings. Each string is a path to an uninitialized field from the top-level message, e.g. “foo.bar[5].baz”.

static FromString(s)

HasField(field_name)

IsInitialized(errors=None)

Checks if all required fields of a message are set.

Args:

errors: A list which, if provided, will be populated with the field

paths of all missing required fields.

Returns:

True iff the specified message has all required fields set.

ListFields()

MergeFrom(msg)

MergeFromString(serialized)

static RegisterExtension(extension_handle)

SS_FIELD_NUMBER = 1

SerializePartialToString()

SerializeToString()

SetInParent()

Sets the _cached_byte_size_dirty bit to true, and propagates this to our listener iff this was a state change.

WhichOneof(oneof_name)

Returns the name of the currently set field inside a oneof, or None.

ss

Magic attribute generated for “ss” proto field.

Module contents