80 lines
2.7 KiB
Text
80 lines
2.7 KiB
Text
= nng_push(7)
|
|
//
|
|
// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
|
|
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
|
|
//
|
|
// This document is supplied under the terms of the MIT License, a
|
|
// copy of which should be located in the distribution where this
|
|
// file was obtained (LICENSE.txt). A copy of the license may also be
|
|
// found online at https://opensource.org/licenses/MIT.
|
|
//
|
|
|
|
== NAME
|
|
|
|
nng_push - push protocol
|
|
|
|
== SYNOPSIS
|
|
|
|
[source,c]
|
|
----
|
|
#include <nng/protocol/pipeline0/push.h>
|
|
----
|
|
|
|
== DESCRIPTION
|
|
|
|
(((protocol, _push_)))
|
|
The ((_push_ protocol)) is one half of a ((pipeline pattern)).
|
|
The other side is the xref:nng_pull.7.adoc[_pull_] protocol.
|
|
|
|
In the pipeline pattern, pushers distribute messages to pullers.
|
|
Each message sent by a pusher will be sent to one of its peer pullers,
|
|
chosen in a round-robin fashion
|
|
from the set of connected peers available for receiving.
|
|
This property makes this pattern useful in ((load-balancing)) scenarios.
|
|
|
|
=== Socket Operations
|
|
|
|
The xref:nng_push_open.3.adoc[`nng_push0_open()`] call creates a pusher socket.
|
|
This socket may be used to send messages, but is unable to receive them.
|
|
Attempts to receive messages will result in `NNG_ENOTSUP`.
|
|
|
|
Send operations will observe flow control (back-pressure), so that
|
|
only peers capable of accepting a message will be considered.
|
|
If no peer is available to receive a message, then the send operation will
|
|
wait until one is available, or the operation times out.
|
|
|
|
NOTE: Although the pipeline protocol honors flow control, and attempts
|
|
to avoid dropping messages, no guarantee of delivery is made.
|
|
Furthermore, as there is no capability for message acknowledgment,
|
|
applications that need reliable delivery are encouraged to consider the
|
|
xref:nng_req.7.adoc[_req_] protocol instead.
|
|
|
|
=== Protocol Versions
|
|
|
|
Only version 0 of this protocol is supported.
|
|
(At the time of writing, no other versions of this protocol have been defined.)
|
|
|
|
=== Protocol Options
|
|
|
|
xref:nng_options.5.adoc#NNG_OPT_SENDBUF[`NNG_OPT_SENDBUF`]::
|
|
|
|
(`int`, 0 - 8192)
|
|
Normally this is set to zero, indicating that send operations are unbuffered.
|
|
In unbuffered operation, send operations will wait until a suitable peer is available to receive the message.
|
|
If this is set to a positive value (up to 8192), then an intermediate buffer is
|
|
provided for the socket with the specified depth (in messages).
|
|
|
|
NOTE: Transport layer buffering may occur in addition to any socket
|
|
buffer determined by this option.
|
|
|
|
=== Protocol Headers
|
|
|
|
The _push_ protocol has no protocol-specific headers.
|
|
|
|
== SEE ALSO
|
|
|
|
[.text-left]
|
|
xref:nng_push_open.3.adoc[nng_push(3)],
|
|
xref:nng_pull.7.adoc[nng_pull(7)],
|
|
xref:nng_req.7.adoc[nng_req(7)],
|
|
xref:nng.7.adoc[nng(7)]
|