syft.messaging.protocol

Module Contents

class syft.messaging.protocol.Protocol(plans: List = None, id: int = None, owner: BaseWorker = None, tags: List[str] = None, description: str = None)

Bases: syft.generic.object.AbstractObject

A Protocol coordinates a sequence of Plans, deploys them on distant workers and run them in a single pass.

It’s a high level object which contains the logic of a complex computation distributed across several workers. The main feature of Protocol is the ability to be sent / searched / fetched back between workers, and finally deployed to identified workers. So a user can design a protocol, upload it to a cloud worker, and any other workers will be able to search for it, download it, and apply the computation program it contains on the workers that it is connected to.

Parameters

  • plans – a list of pairs (worker, plan). “worker” can be either a real worker or a worker id or a string to represent a fictive worker. This last case can be used at creation to specify that two plans should be owned (or not owned) by the same worker at deployment. “plan” can either be a Plan or a PointerPlan.

  • id – the Protocol id

  • owner – the Protocol owner

  • tags – the Protocol tags (used for search)

  • description – the Protocol description

deploy(self, *workers: BaseWorker)

Calling .deploy() sends the plans to the designated workers.

This is done in 2 phases: first, we map the fictive workers provided at creation (named by strings) to the provided workers, and second, we send the corresponding plans to each of them. For the first phase, either there is exactly one real worker per plan or one real worker per fictive_worker. _resolve_workers replaces the fictive workers by the real ones.

Parameters

workers – BaseWorker. The workers to which plans are to be sent

Returns

self

Return type

“Protocol”

Raises

RuntimeError – If protocol is already deployed OR the number of workers provided does not equal the number of fictive workers and does not equal the number of plans

__call__(self, *args, **kwargs)
run(self, *args, **kwargs)

Run the protocol by executing the plans sequentially

The input args provided are sent to the first plan location. This first plan is run and its output is moved to the second plan location, and so on. The final result is returned after all plans have run, and it is composed of pointers to the last plan location.

Raises

RuntimeError – If the protocol has a location attribute and it is not the local worker

request_remote_run(self, location: AbstractWorker, args, kwargs)

Requests protocol execution.

Send a request to execute the protocol on the remote location.

Parameters

  • location – to which worker the request should be sent

  • args – Arguments used as input data for the protocol.

  • kwargs – Named arguments used as input data for the protocol.

Returns

response from request to

execute protocol

Return type

PointerTensor or list of PointerTensors

static find_args_location(args)

Return location if args contain pointers else the local worker

Returns

The location of a pointer if in args, else local

worker

Return type

BaseWorker

send(self, location: BaseWorker)

Send a protocol to a worker, to be fetched by other workers

Parameters

location – BaseWorker. The location to which a protocol is to be sent

static simplify(worker: BaseWorker, protocol: Protocol)

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

Parameters

  • worker (BaseWorker) – the worker doing the serialization

  • protocol (Protocol) – a Protocol object

Returns

a tuple holding the unique attributes of the Protocol object

Return type

tuple

Raises

TypeError – if a plan is not sy.Plan or sy.PointerPlan

static create_from_attributes(worker, id, tags, description, workers_resolved, plans_assignments)

This function reconstructs a Protocol object given its attributes.

Parameters

  • worker – the worker doing the deserialization

  • id – Protocol id

  • tags – Protocol tags

  • description – Protocol description

  • workers_resolved – Flag whether workers are resolved

  • plans_assignments – List of workers/plans IDs

Returns

a Protocol object

Return type

protocol

static detail(worker: BaseWorker, protocol_tuple: Tuple)

This function reconstructs a Protocol object given its attributes in the form of a tuple.

Parameters

  • worker – the worker doing the deserialization

  • protocol_tuple – a tuple holding the attributes of the Protocol

Returns

a Protocol object

Return type

protocol

static bufferize(worker: BaseWorker, protocol: Protocol)

This function takes the attributes of a Protocol and saves them in protobuf ProtocolPB

Parameters

  • worker (BaseWorker) – the worker doing the serialization

  • protocol (Protocol) – a Protocol object

Returns

a protobuf object holding the unique attributes of the Protocol object

Return type

ProtocolPB

Raises

TypeError – if a plan is not sy.Plan or sy.PointerPlan

static unbufferize(worker: AbstractWorker, pb_protocol: ProtocolPB)

This function reconstructs a Protocol object given protobuf object.

Parameters

  • worker – the worker doing the deserialization

  • pb_protocol – a ProtocolPB object

Returns

a Protocol object

Return type

protocol

create_pointer(self, owner: AbstractWorker, garbage_collect_data: bool)

Create a pointer to the protocol

Parameters

  • owner – the owner of the pointer

  • garbage_collect_data – bool

Returns

pointer to the protocol

Return type

PointerProtocol

__repr__(self)
__str__(self)
_assert_is_resolved(self)

Check if protocol has already been resolved

Raises

RuntimeError – If protocol has already been resolved

_resolve_workers(self, workers: Tuple[BaseWorker, ...])

Map the abstract workers (named by strings) to the provided workers and update the plans accordingly

Parameters

workers – Iterable of workers. The workers to map to workers in the protocol