cicada.communicator.interface module

Defines abstract interfaces for network communication.

class cicada.communicator.interface.Communicator

Bases: object

Abstract base class for objects that manage collective communications for secure multiparty computation.

abstract allgather(value)

All-to-all communication.

Note

This method is a collective operation that must be called by all players that are members of the communicator.

Parameters:

value (Any picklable object, required) – Local value that will be sent to all players.

Returns:

values – Collection of objects gathered from every player, in rank order.

Return type:

sequence of object

abstract barrier()

Block the local process until all players have entered the barrier.

Note

This method is a collective operation that must be called by all players that are members of the communicator.

abstract broadcast(*, src, value)

One-to-all communication.

The src player broadcasts a single object to all players.

Note

This method is a collective operation that must be called by all players that are members of the communicator.

Parameters:

• src (int, required) – Rank of the player who is broadcasting.

• value (Any picklable object or None, required) – Value to be broadcast by src. Ignored for all other players.

Returns:

value – The broadcast value.

Return type:

object

abstract free()

Free the communicator.

This should be called if the communicator is no longer needed so that resources can be freed. Note that communicators cannot be reused after they have been freed, a new communicator must be created instead.

abstract gather(*, value, dst)

All-to-one communication.

Every player sends a value to dst.

Note

This method is a collective operation that must be called by all players that are members of the communicator.

Parameters:

• value (Any picklable object, required) – Value to be sent to dst.

• dst (int, required) – Rank of the player who will receive all of the values.

Returns:

values – For the destination player, a sequence of world_size objects received from every player in rank order. For all other players, None.

Return type:

sequence of object or None

abstract gatherv(*, src, value, dst)

Many-to-one communication.

A subset of players each sends a value to dst.

Note

This method is a collective operation that must be called by all players that are members of the communicator.

Parameters:

• src (sequence of int, required) – Rank of each player sending a value.

• value (Any picklable object, or None, required) – Value to be sent to dst.

• dst (int, required) – Rank of the player who will receive all of the values.

Returns:

values – For the destination player, the sequence of values received from the src players in the same order as src. For all other players, None.

Return type:

sequence of object or None

abstract irecv(*, src, tag)

Non-blocking one-to-one communication.

One player (the sender) sends an object to one player (the destination).

Note

Unlike collective operations, this method is only called by the receiver. It must be matched by a call to send() by the sender.

See also

recv

Blocking one-to-one communication.

Parameters:

• src (int, required) – Rank of the sending player.

• tag (int or Tag, required) – User- or library-defined tag identifying the message type to match.

Returns:

result – A special result object that can be used to wait for and access the value sent by the sender. The result object will have a property is_completed which returns a boolean value indicating whether the result has been received; method wait, which will block indefinitely until the result is received; and property value which returns the received value or raises an exception if the value has not been received yet.

Return type:

object

abstract isend(*, value, dst, tag)

Non-blocking one-to-one communication.

One player (the sender) sends an object to one player (the destination).

Note

Unlike collective operations, this method is only called by the sender. It must be matched by a call to recv() by the destination.

See also

send

Blocking one-to-one communication.

Parameters:

• value (Picklable object, required) – Value to be sent.

• dst (int, required) – Rank of the destination player.

• tag (int or Tag, required) – User- or library-defined tag identifying the message type.

Returns:

result – A special result object that can be used to wait until the message has been sent. The result object will have a property is_completed which returns a boolean value indicating whether the result has been sent; and a method wait which will block until the message is sent.

Return type:

object

abstract property rank

Rank of the local player.

Returns:

rank – Player rank, in the range \([0, \text{world_size})\).

Return type:

int

property ranks

List of all ranks managed by this communicator.

Returns:

ranks – The set of all ranks managed by this communicator.

Return type:

sequence of int

abstract recv(*, src, tag)

Blocking one-to-one communication.

One player (the sender) sends an object to one player (the destination).

Note

Unlike collective operations, this method is only called by the receiver. It must be matched by a call to send() by the sender.

See also

irecv

Non-blocking one-to-one communication.

Parameters:

• src (int, required) – Rank of the sending player.

• tag (int or Tag, required) – User- or library-defined tag identifying the message type to match.

Returns:

value – The value sent by the sender.

Return type:

object

abstract scatter(*, src, values)

One-to-all communication.

One player (the sender) sends a different object to every player.

Note

This method is a collective operation that must be called by all players that are members of the communicator.

Parameters:

• src (int, required) – Rank of the sending player.

• values (sequence of picklable object, or None, required) – Collection of objects to be sent, one per player, in rank order.

Returns:

value – The object received by this player.

Return type:

object

abstract scatterv(*, src, values, dst)

One-to-many communication.

One player (the sender) sends a different object to each in a subset of players.

Note

This method is a collective operation that must be called by all players that are members of the communicator.

Parameters:

• src (int, required) – Rank of the sending player.

• values (sequence of picklable object, or None, required) – Collection of objects to be sent, one per recipient.

• dst (sequence of int, required) – Rank of each player receiving an object, in the same order as values.

Returns:

value – The object received by this player, or None if this player wasn’t in the list of recipients.

Return type:

object or None

abstract send(value, dst, tag)

Blocking one-to-one communication.

One player (the sender) sends an object to one player (the destination).

Note

Unlike collective operations, this method is only called by the sender. It must be matched by a call to recv() by the destination.

See also

isend

Non-blocking one-to-one communication.

Parameters:

• value (Picklable object, required) – Value to be sent.

• dst (int, required) – Rank of the destination player.

• tag (int or Tag, required) – User- or library-defined tag identifying the message type.

abstract property world_size

Number of players sharing this communicator.

Returns:

world_size – The number of players sharing this communicator.

Return type:

int

class cicada.communicator.interface.Tag(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Message tags used internally by the library.

Callers can use these tags, or any other int, when calling Communicator.send(), Communicator.recv(), Communicator.isend(), and Communicator.irecv(). Note that negative integers are reserved for use by the library.

ALLGATHER = -1

BARRIER = -2

BEACON = -3

BROADCAST = -4

GATHER = -5

GATHERV = -6

LOGSYNC = -20

PRZS = -30

REVOKE = -7

SCATTER = -8

SCATTERV = -9

SHRINK = -10

cicada.communicator.interface.tagname(tag)

Return a human-readable name for a tag.

Parameters:

tag (int or Tag, required)