Communication
The communication/ directory abstracts how cdough parties exchange messages and offers multiple back-ends.
Contents:
no_copy_communicator/– Zero-copy communicator implementation.communicator.h– Abstract communicator interface.communicator_factory.h– Factory for constructing communicators.mpi_communicator.h– MPI communicator back-end.null_communicator.h– Null communicator for single-process or testing setups.ring.h- definitions for Ring and RingEntry structs.
MPI Communicator
-
class MPICommunicator : public cdough::Communicator
Public Functions
-
inline MPICommunicator(int _currentId, int _msg_tag = 7, const std::string host_prefix = "localhost", double latency = 0, double bandwidth = std::numeric_limits<double>::infinity(), cdough::service::Setting setting = cdough::service::Setting::SAME)
-
inline ~MPICommunicator()
Peer to Peer Communication //.
Send one data element to a chosen party.
- Parameters:
element – The data element to be sent to the party.
id – The index of the recipient party relative to the current party.
Send a vector to a chosen party.
- Parameters:
shares – The data elements to be sent to the party.
id – The index of the recipient party relative to the current party.
size – Number of data elements to be sent.
Receive an element from the chosen party. blocking call.
- Parameters:
element – reference to variable to receive into
id – The index of the sending party relative to the current party.
Receive a vector from some chosen party. blocking call.
- Parameters:
shares – reference to vector to receive into
id – The index of the sending party relative to the current party.
size – Number of data elements to be received.
Single party version of exchange shares.
- Template Parameters:
T –
- Parameters:
sent_shares –
received_shares –
_id –
_size –
Sends and Receives vectors to and from some same party. Subclasses may implement in an arbitrary order, but neither send nor receive should block each other. exchangeShares should block until both calls are completed. Implementations may choose to run send and receive concurrently, or queue the send while waiting on a blocking receive.
- Parameters:
sent_shares – vector to send
received_shares – vector to receive into
id – The index of the other party relative to the current party.
size – Number of data elements to be sent and received.
Exchange shares with two different parties.
- Parameters:
sent_shares –
received_shares –
to_id – relative ID of destination party
from_id – relative ID of source party
size –
Send multiple Vectors to multiple parties at the same time. Vector sizes must match.
- Parameters:
shares – The std::vector of the vectors to be sent.
partyID – The std::vector of the parties to send to.
-
template<typename T>
inline void receiveBroadcast_impl(std::vector<Vector<T>> &shares, std::vector<PartyID> partyID)
-
inline virtual void receiveBroadcast(std::vector<Vector<int8_t>> &shares, std::vector<PartyID> partyID) override
Receive from multiple parties. Vector sizes must match.
- Parameters:
shares – vector of Vectors to be sent
partyID –
-
inline virtual void receiveBroadcast(std::vector<Vector<int16_t>> &shares, std::vector<PartyID> partyID) override
-
inline virtual void receiveBroadcast(std::vector<Vector<int32_t>> &shares, std::vector<PartyID> partyID) override
-
inline virtual void receiveBroadcast(std::vector<Vector<int64_t>> &shares, std::vector<PartyID> partyID) override
-
inline virtual void receiveBroadcast(std::vector<Vector<__int128_t>> &shares, std::vector<PartyID> partyID) override
Send and receive multiple Vectors to and from multiple parties.
- Parameters:
shares – The std::vector of the vectors to be sent.
received_shares – The std::vector of the vectors to be received.
to_id – The std::vector of the parties to send
sharesto.from_id – The std::vector of the parties to receive
received_sharesfrom.
-
inline MPICommunicator(int _currentId, int _msg_tag = 7, const std::string host_prefix = "localhost", double latency = 0, double bandwidth = std::numeric_limits<double>::infinity(), cdough::service::Setting setting = cdough::service::Setting::SAME)
No-copy Communicator
-
class NoCopyCommunicator : public cdough::Communicator
No-copy communicator layer. Builds a ring buffer of pointers to vectors, and sends out each vector sequentially, without introducing extra copies.
Public Functions
-
inline NoCopyCommunicator(int _currentId, const std::vector<int> &socket_map, int _numParties, std::string host_prefix, double latency, double bandwidth, cdough::service::Setting setting = cdough::service::Setting::SAME)
Construct a new No Copy Communicator.
- Parameters:
_currentId – party ID of this node
socket_map – map (stored as a vector) of party IDs to socket file descriptors. The current party ID (i.e.,
_currentID) can contain any value in this map and should be ignored._numParties – The number of parties in this execution
-
inline ~NoCopyCommunicator()
-
template<typename T>
inline void printType(const std::string &name, const std::string &meta) Generic function to print a string along with a type.
- Template Parameters:
T – the type to output
- Parameters:
name – name of the calling function
meta – additional information to output
Send a single generic share. Creates a singleton vector and pushes it to the send ring.
- Template Parameters:
T – type of the share
- Parameters:
share –
_id – relative destination party
Send a shared vector. Pushes the vector to the send ring.
- Template Parameters:
T – underlying type of the shared vector
- Parameters:
_shares –
_id – relative destination party. +1 is the next party, -1 is the previous.
_size – size of the vector (TODO: use size of
_shares)
Receive a single share. Directly calls the
recvfunction.- Template Parameters:
T –
- Parameters:
_share –
_id –
Receive a shared vector. Directly calls the
recvfunction, operating in chunks if the entire vector is not read in a single call.- Template Parameters:
T – underlying type of the shared vector
- Parameters:
_shareVector –
_id – relative source party. +1 is the next party, -1 is the previous.
_size – number of elements to receive
Concurrently send and receive two vectors. Pushes the send vector to the send ring (which is sent out in the background), and then populate the receive vector by reading from the socket.
- Template Parameters:
T –
- Parameters:
sent_shares –
received_shares –
_to_id – relative destination party. +1 is the next party, -1 is the previous.
_from_id – relative source party
_size – number of elements in each vector (TODO: remove)
Send shares to multiple parties.
sharesandpartyIDmust be vectors of the same length.- Template Parameters:
T –
- Parameters:
shares – vector of Vectors; one for each party.
partyID – vector of relative party IDs to send to.
-
template<typename T>
inline void receiveBroadcastGeneric(std::vector<Vector<T>> &shares, std::vector<PartyID> partyID) Receive shares from multiple parties.
sharesandpartyIDmust be vectors of the same length.- Template Parameters:
T –
- Parameters:
shares – vector of Vectors to receive into
partyID – relative source party IDs
Exchange shares to and from multiple parties.
sharesandto_idmust have the same length, as shouldreceived_sharesandfrom_id.- Template Parameters:
T –
- Parameters:
shares – vector of Vectors to send
received_shares – vector of Vectors to receive into
to_id – relative destination IDs
from_id – relative source IDs
Peer to Peer Communication //.
Send one data element to a chosen party.
- Parameters:
element – The data element to be sent to the party.
id – The index of the recipient party relative to the current party.
Send a vector to a chosen party.
- Parameters:
shares – The data elements to be sent to the party.
id – The index of the recipient party relative to the current party.
size – Number of data elements to be sent.
Receive an element from the chosen party. blocking call.
- Parameters:
element – reference to variable to receive into
id – The index of the sending party relative to the current party.
Receive a vector from some chosen party. blocking call.
- Parameters:
shares – reference to vector to receive into
id – The index of the sending party relative to the current party.
size – Number of data elements to be received.
Sends and Receives vectors to and from some same party. Subclasses may implement in an arbitrary order, but neither send nor receive should block each other. exchangeShares should block until both calls are completed. Implementations may choose to run send and receive concurrently, or queue the send while waiting on a blocking receive.
- Parameters:
sent_shares – vector to send
received_shares – vector to receive into
id – The index of the other party relative to the current party.
size – Number of data elements to be sent and received.
Exchange shares with two different parties.
- Parameters:
sent_shares –
received_shares –
to_id – relative ID of destination party
from_id – relative ID of source party
size –
Send multiple Vectors to multiple parties at the same time. Vector sizes must match.
- Parameters:
shares – The std::vector of the vectors to be sent.
partyID – The std::vector of the parties to send to.
-
inline virtual void receiveBroadcast(std::vector<Vector<int8_t>> &shares, std::vector<PartyID> partyID)
Receive from multiple parties. Vector sizes must match.
- Parameters:
shares – vector of Vectors to be sent
partyID –
-
inline virtual void receiveBroadcast(std::vector<Vector<int16_t>> &shares, std::vector<PartyID> partyID)
-
inline virtual void receiveBroadcast(std::vector<Vector<int32_t>> &shares, std::vector<PartyID> partyID)
-
inline virtual void receiveBroadcast(std::vector<Vector<int64_t>> &shares, std::vector<PartyID> partyID)
-
inline virtual void receiveBroadcast(std::vector<Vector<__int128_t>> &shares, std::vector<PartyID> partyID)
Send and receive multiple Vectors to and from multiple parties.
- Parameters:
shares – The std::vector of the vectors to be sent.
received_shares – The std::vector of the vectors to be received.
to_id – The std::vector of the parties to send
sharesto.from_id – The std::vector of the parties to receive
received_sharesfrom.
-
inline PartyInfoBasic &get_party(int id)
Get the party info object for the given (absolute) party. Performs a bounds check on the ID and asserts that the struct pointer is not null.
- Parameters:
id –
- Returns:
PartyInfoBasic&
-
inline NoCopyCommunicator(int _currentId, const std::vector<int> &socket_map, int _numParties, std::string host_prefix, double latency, double bandwidth, cdough::service::Setting setting = cdough::service::Setting::SAME)
-
namespace cdough
-
template<typename Engine>
class NoCopyCommunicatorFactory : public cdough::CommunicatorFactory<NoCopyCommunicatorFactory<Engine>> - #include <no_copy_communicator_factory.h>
Factor for the
nocopycommunicator to interface with theCommunicatorFactoryAPI.Public Functions
-
inline std::unique_ptr<Communicator> create()
-
inline void start()
-
inline int getPartyId() const
-
inline int getNumParties() const
-
inline void blockingReady()
Private Members
-
int partyId
-
int numParties
-
const int threadsNum_
-
const std::string host_prefix
-
std::vector<std::vector<int>> socketMaps_
Vector of socket maps for each cdough thread. Each element of the outer vector is assigned to a thread. The inner vector maps from party ID to socket file descriptor:
socket_maps[Thread #][Party ID] -> Socket file descriptor
NOTE: this used to be a vector<map<int, int>>, but this led to a concurrent write and thus an infrequent race condition.
-
inline std::unique_ptr<Communicator> create()
-
template<typename Engine>
-
struct NoCopyRingEntry
- #include <no_copy_ring.h>
A single entry in the NoCopy ring.
-
class NoCopyRing
- #include <no_copy_ring.h>
The NoCopy circular ring buffer. Contains a read and write index, both of which are updated atomically, and a dynamically-allocated array of ring entries.
As data is added to the ring buffer, the write index is incremented. As data is read and sent out on the socket, the read index is incremented. If the read index cannot be incremented, the buffer is empty. If the write index cannot be incremented, the buffer is full.
Public Functions
-
~NoCopyRing()
-
int getWriteIndex() const
-
int getReadIndex() const
-
int nextIndex(int) const
Returns the next index in the ring buffer (mod the ring size)
- Parameters:
index –
- Returns:
int
-
bool isRingFull() const
Checks if the ring is full: that is,
readIndexis the next index afterwriteIndex.- Returns:
true the ring is full
- Returns:
false it is not
-
bool isRingEmpty() const
Checks if the ring is empty: that is,
readIndexandwriteIndexare the same.- Returns:
true the ring is empty
- Returns:
false it is not
-
template<typename T>
int push(const cdough::Vector<T>&) Push a (pointer to a) Vector onto the buffer. Be careful about data lifetimes: if the passed vectorData goes out of scope in the caller, undefined data may be sent. This function expects vectorData to remain unmodified until it is sent.
- Template Parameters:
T –
- Parameters:
vectorData – the const Vector to push onto the buffer.
- Returns:
int
-
NoCopyRingEntry *currentEntry() const
Wait until the ring is not empty, then return a pointer to the current entry.
- Returns:
NoCopyRingEntry*
-
void pop(NoCopyRingEntry*)
Remove the first element (at readIndex) from the ring buffer.
- Parameters:
entry –
-
void wait(int) const
Wait until the readIndex equals pushIndex.
- Parameters:
pushIndex –
Private Members
-
std::atomic<uint32_t> writeIndex = 0
-
std::atomic<uint32_t> readIndex = 0
-
int ring_size
-
NoCopyRingEntry *ring_array
-
~NoCopyRing()
Base Classes & Utilities
-
class Communicator
The base communicator class. All communicators must inherit from this class.
Subclassed by cdough::MPICommunicator, cdough::NoCopyCommunicator, cdough::NullCommunicator
Public Functions
-
inline Communicator(PartyID _currentId, std::string host_prefix = "localhost", double latency = 0, double bandwidth = std::numeric_limits<double>::infinity(), service::Setting setting = service::Setting::SAME)
Initializes the communicator base with the current party index.
- Parameters:
_currentId – The absolute index of the party in the parties ring.
-
inline virtual ~Communicator()
-
inline size_t getBytesSent() const
-
inline double getLatency()
Get the communicator’s latency in milliseconds. This implementation returns a static value, but future implementations may directly measure the value in the caller.
- Returns:
double
-
inline double getBandwidth()
Get the communicator’s bandwdith in Gbps. This implementation returns a static value, but future implementations may directly measure the value in the caller.
- Returns:
double
-
inline service::Setting getSetting() const
Get the network setting (same/lan/wan) for this execution.
- Returns:
Peer to Peer Communication //.
Send one data element to a chosen party.
- Parameters:
element – The data element to be sent to the party.
id – The index of the recipient party relative to the current party.
Send a vector to a chosen party.
- Parameters:
shares – The data elements to be sent to the party.
id – The index of the recipient party relative to the current party.
size – Number of data elements to be sent.
Receive an element from the chosen party. blocking call.
- Parameters:
element – reference to variable to receive into
id – The index of the sending party relative to the current party.
Receive a vector from some chosen party. blocking call.
- Parameters:
shares – reference to vector to receive into
id – The index of the sending party relative to the current party.
size – Number of data elements to be received.
Sends and Receives vectors to and from some same party. Subclasses may implement in an arbitrary order, but neither send nor receive should block each other. exchangeShares should block until both calls are completed. Implementations may choose to run send and receive concurrently, or queue the send while waiting on a blocking receive.
- Parameters:
sent_shares – vector to send
received_shares – vector to receive into
id – The index of the other party relative to the current party.
size – Number of data elements to be sent and received.
Exchange shares with two different parties.
- Parameters:
sent_shares –
received_shares –
to_id – relative ID of destination party
from_id – relative ID of source party
size –
Send multiple Vectors to multiple parties at the same time. Vector sizes must match.
- Parameters:
shares – The std::vector of the vectors to be sent.
partyID – The std::vector of the parties to send to.
-
virtual void receiveBroadcast(std::vector<Vector<int8_t>> &shares, std::vector<PartyID> partyID) = 0
Receive from multiple parties. Vector sizes must match.
- Parameters:
shares – vector of Vectors to be sent
partyID –
-
virtual void receiveBroadcast(std::vector<Vector<int16_t>> &shares, std::vector<PartyID> partyID) = 0
-
virtual void receiveBroadcast(std::vector<Vector<int32_t>> &shares, std::vector<PartyID> partyID) = 0
-
virtual void receiveBroadcast(std::vector<Vector<int64_t>> &shares, std::vector<PartyID> partyID) = 0
-
virtual void receiveBroadcast(std::vector<Vector<__int128_t>> &shares, std::vector<PartyID> partyID) = 0
-
inline void receiveBroadcast(std::vector<Vector<__uint128_t>> &shares, std::vector<PartyID> partyID)
Send and receive multiple Vectors to and from multiple parties.
- Parameters:
shares – The std::vector of the vectors to be sent.
received_shares – The std::vector of the vectors to be received.
to_id – The std::vector of the parties to send
sharesto.from_id – The std::vector of the parties to receive
received_sharesfrom.
Public Members
-
std::string host_prefix
Protected Functions
-
inline Communicator(PartyID _currentId, std::string host_prefix = "localhost", double latency = 0, double bandwidth = std::numeric_limits<double>::infinity(), service::Setting setting = service::Setting::SAME)
-
template<typename InnerFactory>
class CommunicatorFactory A factory or a communicator object. Parameterized by the subclass type.
- Template Parameters:
InnerFactory –
Public Functions
-
virtual ~CommunicatorFactory() = default
-
inline std::unique_ptr<Communicator> create()
Create a unique pointer to a new communicator.
- Returns:
std::unique_ptr<Communicator>
-
inline void start()
Start the communicator.
-
inline int getPartyId() const
Get the Party ID of this node.
- Returns:
int
-
inline void blockingReady()
If this communicator is blocking, wait until it is ready.
-
inline auto getSetting() const
Get the network setting (same/lan/wan) according to the runtime.
- Returns:
The Setting enum value for this execution.
Protected Attributes
-
double latency
pairwise latency of this communicator, milliseconds. Passed into Communicator
-
double bandwidth
pairwise bandwidth of this communicator, Gbps. Passed into Communicator
-
class NullCommunicator : public cdough::Communicator
Public Functions
-
inline NullCommunicator(std::string host_prefix = "localhost")
Null Communicator that does nothing for the Plaintext 1PC test protocol.
-
inline ~NullCommunicator()
-
template<typename T>
inline void checkMapping(const Vector<T> &v) Confirm that
vdoes not have a mapping before sending it.- Template Parameters:
T –
- Parameters:
v –
Peer to Peer Communication //.
Send one data element to a chosen party.
- Parameters:
element – The data element to be sent to the party.
id – The index of the recipient party relative to the current party.
Send a vector to a chosen party.
- Parameters:
shares – The data elements to be sent to the party.
id – The index of the recipient party relative to the current party.
size – Number of data elements to be sent.
Receive an element from the chosen party. blocking call.
- Parameters:
element – reference to variable to receive into
id – The index of the sending party relative to the current party.
Receive a vector from some chosen party. blocking call.
- Parameters:
shares – reference to vector to receive into
id – The index of the sending party relative to the current party.
size – Number of data elements to be received.
Copy
sent_sharesintoreceived_shares- Parameters:
sent_shares –
received_shares –
to_id –
from_id –
_size –
Sends and Receives vectors to and from some same party. Subclasses may implement in an arbitrary order, but neither send nor receive should block each other. exchangeShares should block until both calls are completed. Implementations may choose to run send and receive concurrently, or queue the send while waiting on a blocking receive.
- Parameters:
sent_shares – vector to send
received_shares – vector to receive into
id – The index of the other party relative to the current party.
size – Number of data elements to be sent and received.
Send multiple Vectors to multiple parties at the same time. Vector sizes must match.
- Parameters:
shares – The std::vector of the vectors to be sent.
partyID – The std::vector of the parties to send to.
-
inline virtual void receiveBroadcast(std::vector<Vector<int8_t>> &shares, std::vector<PartyID> partyID)
Do nothing.
- Parameters:
shares –
partyID –
-
inline virtual void receiveBroadcast(std::vector<Vector<int16_t>> &shares, std::vector<PartyID> partyID)
-
inline virtual void receiveBroadcast(std::vector<Vector<int32_t>> &shares, std::vector<PartyID> partyID)
-
inline virtual void receiveBroadcast(std::vector<Vector<int64_t>> &shares, std::vector<PartyID> partyID)
-
inline virtual void receiveBroadcast(std::vector<Vector<__int128_t>> &shares, std::vector<PartyID> partyID)
Copy each element of
sharesintoreceived_shares. Lengths must match.- Parameters:
shares –
received_shares –
to_id –
from_id –
Private Members
-
int numParties
-
inline NullCommunicator(std::string host_prefix = "localhost")