1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

// Copyright (c) 2015-2017 Contributors as noted in the AUTHORS file.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0>
// or the MIT license <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
// This file may not be copied, modified, or distributed except according to those terms.

//! Scalability protocols provided by scaproust

pub mod pair;
pub mod push;
pub mod pull;
pub mod req;
pub mod rep;
pub mod publ;
pub mod sub;
pub mod surv;
pub mod resp;
pub mod bus;

mod pipes;
mod priolist;
mod policy;

use core::Scheduled;

#[doc(hidden)]
pub type Timeout = Option<Scheduled>;

/// **One-to-one protocol**   
///   
/// Pair protocol is the simplest and least scalable scalability protocol. 
/// It allows scaling by breaking the application in exactly two pieces. 
/// For example, if a monolithic application handles both accounting and agenda of HR department, 
/// it can be split into two applications (accounting vs. HR) that are run on two separate servers. 
/// These applications can then communicate via `Pair` sockets. 
/// The downside of this protocol is that its scaling properties are very limited. 
/// Splitting the application into two pieces allows to scale the two servers. 
/// To add the third server to the cluster, application has to be split once more, 
/// say by separating HR functionality into hiring module and salary computation module. 
/// Whenever possible, try to use one of the more scalable protocols instead.  
///  
/// Socket for communication with exactly one peer.
/// Each party can send messages at any time. 
/// If the peer is not available or send buffer is full subsequent calls to [send](struct.Socket.html#method.send) 
/// will block until it’s possible to send the message.
pub const PAIR:       u16 = (    16)    ;


/// **Publish/subscribe protocol**   
///   
/// Broadcasts messages to multiple destinations.
/// Messages are sent from `Pub` sockets and will only be received 
/// by `Sub` sockets that have subscribed to the matching topic. 
/// Topic is an arbitrary sequence of bytes at the beginning of the message body. 
/// The `Sub` socket will determine whether a message should be delivered 
/// to the user by comparing the subscribed topics to the bytes initial bytes 
/// in the incomming message, up to the size of the topic.  
/// Subscribing via [`Socket::set_option`](struct.Socket.html#method.set_option) and [`ConfigOption::Subscribe`](../enum.ConfigOption.html#variant.Subscribe)
/// Will match any message with intial 5 bytes being "Hello", for example, message "Hello, World!" will match.
/// Topic with zero length matches any message.
/// If the socket is subscribed to multiple topics, 
/// message matching any of them will be delivered to the user.
/// Since the filtering is performed on the Subscriber side, 
/// all the messages from Publisher will be sent over the transport layer.
/// The entire message, including the topic, is delivered to the user.  
///   
/// This socket is used to distribute messages to multiple destinations. Receive operation is not defined.
pub const PUB:        u16 = (2 * 16)    ;


/// **Publish/subscribe protocol**   
///   
/// Receives messages from the publisher. 
/// Only messages that the socket is subscribed to are received. 
/// When the socket is created there are no subscriptions 
/// and thus no messages will be received. 
/// Send operation is not defined on this socket.
pub const SUB:        u16 = (2 * 16) + 1;


/// **Request/reply protocol**   
///   
/// This protocol is used to distribute the workload among multiple stateless workers.
/// Please note that request/reply applications should be stateless.
/// It’s important to include all the information necessary to process the request in the request itself, 
/// including information about the sender or the originator of the request if this is necessary to respond to the request.
/// Sender information cannot be retrieved from the underlying socket connection since, 
/// firstly, transports like IPC may not have a firm notion of a message origin. 
/// Secondly, transports that have some notion may not have a reliable one 
/// - a TCP disconnect may mean a new sender, or it may mean a temporary loss in network connectivity.
/// For this reason, sender information must be included by the application if required. 
/// Allocating 6 randomly-generated bytes in the message for the lifetime of the connection is sufficient for most purposes. 
/// For longer-lived applications, an UUID is more suitable.  
///   
/// Used to implement the client application that sends requests and receives replies.
pub const REQ:        u16 = (3 * 16)    ;


/// **Request/reply protocol**   
///   
/// Used to implement the stateless worker that receives requests and sends replies.
pub const REP:        u16 = (3 * 16) + 1;


/// **Pipeline protocol**   
///   
/// Fair queues messages from the previous processing step and load balances them among instances of the next processing step.  
///   
/// This socket is used to send messages to a cluster of load-balanced nodes. Receive operation is not implemented on this socket type.
pub const PUSH:       u16 = (5 * 16)    ;


/// **Pipeline protocol**   
///   
/// This socket is used to receive a message from a cluster of nodes. Send operation is not implemented on this socket type.
pub const PULL:       u16 = (5 * 16) + 1;


/// **Survey protocol**   
///   
/// Allows to broadcast a survey to multiple locations and gather the responses.  
///   
/// Used to send the survey. The survey is delivered to all the connected respondents. 
/// Once the query is sent, the socket can be used to receive the responses. 
/// When the survey deadline expires, receive will return ETIMEDOUT error.
pub const SURVEYOR:   u16 = (6 * 16) + 2;


/// **Survey protocol**   
///   
/// Use to respond to the survey. 
/// Survey is received using receive function, response is sent using send function. 
/// This socket can be connected to at most one peer.
pub const RESPONDENT: u16 = (6 * 16) + 3;


/// **Message bus protocol**   
///   
/// Broadcasts messages from any node to all other nodes in the topology. 
/// The socket should never receives messages that it sent itself.
/// This pattern scales only to local level (within a single machine or within a single LAN). 
/// Trying to scale it further can result in overloading individual nodes with messages.  
///   
/// _Warning For bus topology to function correctly, user is responsible for ensuring 
/// that path from each node to any other node exists within the topology._  
///   
/// Sent messages are distributed to all nodes in the topology. 
/// Incoming messages from all other nodes in the topology are fair-queued in the socket.
pub const BUS:        u16 = (7 * 16)    ;