syft.messaging.message

This file exists as the Python encoding of all Message types that Syft sends over the network. It is an important bottleneck in the system, impacting both security, performance, and cross-platform compatability. As such, message types should strive to not be framework specific (i.e., Torch, Tensorflow, etc.).

All Syft message types extend the Message class.

Module Contents

class syft.messaging.message.Message(contents=None)

All syft message types extend this class

All messages in the pysyft protocol extend this class. This abstraction requires that every message has an integer type, which is important because this integer is what determines how the message is handled when a BaseWorker receives it.

Additionally, this type supports a default simplifier and detailer, which are important parts of PySyft’s serialization and deserialization functionality. You can read more abouty detailers and simplifiers in syft/serde/serde.py.

property contents(self)

Return a tuple with the contents of the message (backwards compatability)

Some of our codebase still assumes that all message types have a .contents attribute. However, the contents attribute is very opaque in that it doesn’t put any constraints on what the contents might be. Some message types can be more efficient by storing their contents more explicitly (see Operation). They can override this property to return a tuple view on their other properties.

_simplify(self)
static simplify(worker: AbstractWorker, ptr: Message)

This function takes the attributes of a Message and saves them in a tuple. The detail() method runs the inverse of this method. :param worker: a reference to the worker doing the serialization :type worker: AbstractWorker :param ptr: a Message :type ptr: Message

Returns

a tuple holding the unique attributes of the message

Return type

tuple

Examples

data = simplify(ptr)

static detail(worker: AbstractWorker, msg_tuple: tuple)

This function takes the simplified tuple version of this message and converts it into a message. The simplify() method runs the inverse of this method.

This method shouldn’t get called very often. It exists as a backup but in theory every message type should have its own detailer.

Parameters

  • worker (AbstractWorker) – a reference to the worker necessary for detailing. Read syft/serde/serde.py for more information on why this is necessary.

  • msg_tuple (Tuple) – the raw information being detailed.

Returns

a Operation.

Return type

ptr (Message)

Examples

message = detail(sy.local_worker, msg_tuple)

__str__(self)

Return a human readable version of this message

__repr__(self)

Return a human readable version of this message

class syft.messaging.message.Operation(cmd_name, cmd_owner, cmd_args, cmd_kwargs, return_ids)

Bases: syft.messaging.message.Message

All syft operations use this message type

In Syft, an operation is when one worker wishes to tell another worker to do something with objects contained in the worker._objects registry (or whatever the official object store is backed with in the case that it’s been overridden). Semantically, one could view all Messages as a kind of operation, but when we say operation this is what we mean. For example, telling a worker to take two tensors and add them together is an operation. However, sending an object from one worker to another is not an operation (and would instead use the ObjectMessage type).

property contents(self)

Return a tuple with the contents of the operation (backwards compatability)

Some of our codebase still assumes that all message types have a .contents attribute. However, the contents attribute is very opaque in that it doesn’t put any constraints on what the contents might be. Since we know this message is a operation, we instead choose to store contents in two pieces, self.message and self.return_ids, which allows for more efficient simplification (we don’t have to simplify return_ids because they are always a list of integers, meaning they’re already simplified).

static simplify(worker: AbstractWorker, ptr: Operation)

This function takes the attributes of a Operation and saves them in a tuple :param worker: a reference to the worker doing the serialization :type worker: AbstractWorker :param ptr: a Message :type ptr: Operation

Returns

a tuple holding the unique attributes of the message

Return type

tuple

Examples

data = simplify(ptr)

static detail(worker: AbstractWorker, msg_tuple: tuple)

This function takes the simplified tuple version of this message and converts it into a Operation. The simplify() method runs the inverse of this method.

Parameters

  • worker (AbstractWorker) – a reference to the worker necessary for detailing. Read syft/serde/serde.py for more information on why this is necessary.

  • msg_tuple (Tuple) – the raw information being detailed.

Returns

a Operation.

Return type

ptr (Operation)

Examples

message = detail(sy.local_worker, msg_tuple)

static bufferize(worker: AbstractWorker, operation: Operation)

This function takes the attributes of a Operation and saves them in Protobuf :param worker: a reference to the worker doing the serialization :type worker: AbstractWorker :param ptr: a Message :type ptr: Operation

Returns

a Protobuf message holding the unique attributes of the message

Return type

protobuf_obj

Examples

data = bufferize(message)

static unbufferize(worker: AbstractWorker, protobuf_obj: OperationMessagePB)

This function takes the Protobuf version of this message and converts it into an Operation. The bufferize() method runs the inverse of this method.

Parameters

  • worker (AbstractWorker) – a reference to the worker necessary for detailing. Read syft/serde/serde.py for more information on why this is necessary.

  • protobuf_obj (OperationPB) – the Protobuf message

Returns

an Operation

Return type

obj (Operation)

Examples

message = unbufferize(sy.local_worker, protobuf_msg)

static _bufferize_args(worker: AbstractWorker, args: list)
static _bufferize_arg(worker: AbstractWorker, arg: object)
static _unbufferize_args(worker: AbstractWorker, protobuf_args: list)
static _unbufferize_arg(worker: AbstractWorker, protobuf_arg: ArgPB)
class syft.messaging.message.ObjectMessage(contents)

Bases: syft.messaging.message.Message

Send an object to another worker using this message type.

When a worker has an object in its local object repository (such as a tensor) and it wants to send that object to another worker (and delete its local copy), it uses this message type to do so.

static detail(worker: AbstractWorker, msg_tuple: tuple)

This function takes the simplified tuple version of this message and converts it into an ObjectMessage. The simplify() method runs the inverse of this method.

Parameters

  • worker (AbstractWorker) – a reference to the worker necessary for detailing. Read syft/serde/serde.py for more information on why this is necessary.

  • msg_tuple (Tuple) – the raw information being detailed.

Returns

a ObjectMessage.

Return type

ptr (ObjectMessage)

Examples

message = detail(sy.local_worker, msg_tuple)

static bufferize(worker: AbstractWorker, message: ObjectMessage)

This function takes the attributes of an Object Message and saves them in a protobuf object :param message: an ObjectMessage :type message: ObjectMessage

Returns

a protobuf object holding the unique attributes of the object message

Return type

protobuf

Examples

data = bufferize(object_message)

static unbufferize(worker: AbstractWorker, protobuf_obj: ObjectMessagePB)
class syft.messaging.message.ObjectRequestMessage(contents)

Bases: syft.messaging.message.Message

Request another worker to send one of its objects

If ObjectMessage pushes an object to another worker, this Message type pulls an object from another worker. It also assumes that the other worker will delete it’s local copy of the object after sending it to you.

static detail(worker: AbstractWorker, msg_tuple: tuple)

This function takes the simplified tuple version of this message and converts it into an ObjectRequestMessage. The simplify() method runs the inverse of this method.

Parameters

  • worker (AbstractWorker) – a reference to the worker necessary for detailing. Read syft/serde/serde.py for more information on why this is necessary.

  • msg_tuple (Tuple) – the raw information being detailed.

Returns

a ObjectRequestMessage.

Return type

ptr (ObjectRequestMessage)

Examples

message = detail(sy.local_worker, msg_tuple)

class syft.messaging.message.IsNoneMessage(contents)

Bases: syft.messaging.message.Message

Check if a worker does not have an object with a specific id.

Occasionally we need to verify whether or not a remote worker has a specific object. To do so, we send an IsNoneMessage, which returns True if the object (such as a tensor) does NOT exist.

static detail(worker: AbstractWorker, msg_tuple: tuple)

This function takes the simplified tuple version of this message and converts it into an IsNoneMessage. The simplify() method runs the inverse of this method.

Parameters

  • worker (AbstractWorker) – a reference to the worker necessary for detailing. Read syft/serde/serde.py for more information on why this is necessary.

  • msg_tuple (Tuple) – the raw information being detailed.

Returns

a IsNoneMessage.

Return type

ptr (IsNoneMessage)

Examples

message = detail(sy.local_worker, msg_tuple)

class syft.messaging.message.GetShapeMessage(contents)

Bases: syft.messaging.message.Message

Get the shape property of a tensor in PyTorch

We needed to have a special message type for this because .shape had some constraints in the older version of PyTorch.

static detail(worker: AbstractWorker, msg_tuple: tuple)

This function takes the simplified tuple version of this message and converts it into an GetShapeMessage. The simplify() method runs the inverse of this method.

Parameters

  • worker (AbstractWorker) – a reference to the worker necessary for detailing. Read syft/serde/serde.py for more information on why this is necessary.

  • msg_tuple (Tuple) – the raw information being detailed.

Returns

a GetShapeMessage.

Return type

ptr (GetShapeMessage)

Examples

message = detail(sy.local_worker, msg_tuple)

class syft.messaging.message.ForceObjectDeleteMessage(contents)

Bases: syft.messaging.message.Message

Garbage collect a remote object

This is the dominant message for garbage collection of remote objects. When a pointer is deleted, this message is triggered by default to tell the object being pointed to to also delete itself.

static detail(worker: AbstractWorker, msg_tuple: tuple)

This function takes the simplified tuple version of this message and converts it into an ForceObjectDeleteMessage. The simplify() method runs the inverse of this method.

Parameters

  • worker (AbstractWorker) – a reference to the worker necessary for detailing. Read syft/serde/serde.py for more information on why this is necessary.

  • msg_tuple (Tuple) – the raw information being detailed.

Returns

a ForceObjectDeleteMessage.

Return type

ptr (ForceObjectDeleteMessage)

Examples

message = detail(sy.local_worker, msg_tuple)

class syft.messaging.message.SearchMessage(contents)

Bases: syft.messaging.message.Message

A client queries for a subset of the tensors on a remote worker using this type

For some workers like SocketWorker we split a worker into a client and a server. For this configuration, a client can request to search for a subset of tensors on the server using this message type (this could also be called a “QueryMessage”).

static detail(worker: AbstractWorker, msg_tuple: tuple)

This function takes the simplified tuple version of this message and converts it into an SearchMessage. The simplify() method runs the inverse of this method.

Parameters

  • worker (AbstractWorker) – a reference to the worker necessary for detailing. Read syft/serde/serde.py for more information on why this is necessary.

  • msg_tuple (Tuple) – the raw information being detailed.

Returns

a SearchMessage.

Return type

ptr (SearchMessage)

Examples

message = detail(sy.local_worker, msg_tuple)

class syft.messaging.message.PlanCommandMessage(command_name: str, message: tuple)

Bases: syft.messaging.message.Message

Message used to execute a command related to plans.

property contents(self)

Returns a tuple with the contents of the operation (backwards compatability).

static simplify(worker: AbstractWorker, ptr: PlanCommandMessage)

This function takes the attributes of a PlanCommandMessage and saves them in a tuple

Parameters
Returns

a tuple holding the unique attributes of the message

Return type

tuple

static detail(worker: AbstractWorker, msg_tuple: tuple)

This function takes the simplified tuple version of this message and converts it into a PlanCommandMessage. The simplify() method runs the inverse of this method.

Parameters

  • worker (AbstractWorker) – a reference to the worker necessary for detailing. Read syft/serde/serde.py for more information on why this is necessary.

  • msg_tuple (Tuple) – the raw information being detailed.

Returns

a PlanCommandMessage.

Return type

ptr (PlanCommandMessage)