From edd3b6bc34f211bd3d58642d0c69ce1b5bb9dc3b Mon Sep 17 00:00:00 2001 From: gdamore Date: Thu, 9 Oct 2025 01:22:20 +0000 Subject: deploy: 9c834956456924df7c885ab8b79573721acaff5c --- ref/api/ctx.html | 64 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 32 insertions(+), 32 deletions(-) (limited to 'ref/api/ctx.html') diff --git a/ref/api/ctx.html b/ref/api/ctx.html index 0aa22a6e..7130e568 100644 --- a/ref/api/ctx.html +++ b/ref/api/ctx.html @@ -246,33 +246,33 @@

Contexts

Contexts in Scalability Protocols provide for isolation of protocol-specific state machines and associated data, allowing multiple concurrent state machines (or transactions) -to coexist on a single socket.

-

For example, a REP server may wish to allow many requests to be serviced concurrently, +to coexist on a single socket.

+

For example, a REP server may wish to allow many requests to be serviced concurrently, even though some jobs may take significant time to process. Contexts provide for this ability.

Not all protocols have contexts, because many protocols simply have no state to manage. The following protocols support contexts:

For these protocols, the socket will also have a single, default, context that is used when performing send or receive operations on the socket directly.

Other protocols are stateless, at least with respect to message processing, and have no use for -contexts. For the same reason, raw mode sockets do not support contexts.

+contexts. For the same reason, raw mode sockets do not support contexts.

tip

-

Developers with experience with [libnanomsg] may be used to using raw sockets for concurrency. +

Developers with experience with [libnanomsg] may be used to using raw sockets for concurrency. Contexts provide a superior solution, as they are much easier to use, less error prone, and allow for easy control of the amount of concurrency used on any given socket.

One drawback of contexts is that they cannot be used with file descriptor polling using -nng_socket_get_recv_poll_fd or nng_socket_get_send_poll_fd.

+nng_socket_get_recv_poll_fd or nng_socket_get_send_poll_fd.

Context Structure

#define NNG_CTX_INITIALIZER // opaque value
 
@@ -285,15 +285,15 @@ to ensure that it cannot be confused with a valid open context.

 
Creating a Context

 
int nng_ctx_open(nng_ctx *ctxp, nng_socket s);
 

-
The nng_ctx_open function creates a separate context to be used with the socket s,
+
The nng_ctx_open function creates a separate context to be used with the socket s,
 and returns it at the location pointed by ctxp.

 
Context Identity

 
int nng_ctx_id(nng_ctx c);
 

 
The nng_ctx_id function returns a positive identifier for the context c if it is valid.
 Otherwise it returns -1.

-
A context is considered valid if it was ever opened with nng_ctx_open function.
-Contexts that are allocated on the stack or statically should be initialized with the macro NNG_CTX_INITIALIZER
+
A context is considered valid if it was ever opened with nng_ctx_open function.
+Contexts that are allocated on the stack or statically should be initialized with the macro NNG_CTX_INITIALIZER
 to ensure that they cannot be confused with a valid context before they are opened.

 
Closing a Context

 
int nng_ctx_close(nng_ctx ctx);
@@ -309,7 +309,7 @@ call is executed may also return with an NNG_ECLOSED result.

   
   note
 

-
Closing the socket associated with ctx using nng_socket_close also closes this context.

+
Closing the socket associated with ctx using nng_socket_close also closes this context.

 
 
Sending Messages

 
int nng_ctx_sendmsg(nng_ctx ctx, nng_msg *msg, int flags);
@@ -325,21 +325,21 @@ messages over the socket s. The differences in their behaviors are as f
 
The semantics of what sending a message means varies from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 Additionally, some protocols may not support sending at all or may require other pre-conditions first.
-(For example, REP sockets cannot normally send data until they have first received a request,
-while SUB sockets can only receive data and never send it.)

+(For example, REP sockets cannot normally send data until they have first received a request,
+while SUB sockets can only receive data and never send it.)

 
 
nng_ctx_sendmsg

 
The nng_ctx_sendmsg function sends the msg over the context ctx.

 
If this function returns zero, then the socket will dispose of msg when the transmission is complete.
 If the function returns a non-zero status, then the call retains the responsibility for disposing of msg.

-
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
-cannot accept more data for sending. In such a case, it will return NNG_EAGAIN.

+
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
+cannot accept more data for sending. In such a case, it will return NNG_EAGAIN.

 
nng_ctx_send

-
The nng_ctx_send function sends a message asynchronously, using the nng_aio aio, over the context ctx.
-The message to send must have been set on aio using the nng_aio_set_msg function.

+
The nng_ctx_send function sends a message asynchronously, using the nng_aio aio, over the context ctx.
+The message to send must have been set on aio using the nng_aio_set_msg function.

 
If the operation completes successfully, then the context will have disposed of the message.
 However, if it fails, then callback of aio should arrange for a final disposition of the message.
-(The message can be retrieved from aio with nng_aio_get_msg.)

+(The message can be retrieved from aio with nng_aio_get_msg.)

 
Note that callback associated with aio may be called before the message is finally delivered to the recipient.
 For example, the message may be sitting in queue, or located in TCP buffers, or even in flight.

 

@@ -349,7 +349,7 @@ For example, the message may be sitting in queue, or located in TCP buffers, or
 

 
This is the preferred function to use for sending data on a context. While it does require a few extra
 steps on the part of the application, the lowest latencies and highest performance will be achieved by using
-this function instead of nng_ctx_sendmsg.

+this function instead of nng_ctx_sendmsg.

 

 
Receiving Messages

 
int nng_ctx_recvmsg(nng_ctx ctx, nng_msg **msgp, int flags);
@@ -365,15 +365,15 @@ messages over the context ctx. The differences in their behaviors are a
 
The semantics of what receiving a message means varies from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 Additionally, some protocols may not support receiving at all or may require other pre-conditions first.
-(For example, REQ sockets cannot normally receive data until they have first sent a request.)

+(For example, REQ sockets cannot normally receive data until they have first sent a request.)

 
 
nng_recvmsg

-
The nng_ctx_recvmsg function receives a message and stores a pointer to the nng_msg for that message in msgp.

-
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
-has no messages available to receive. In such a case, it will return NNG_EAGAIN.

+
The nng_ctx_recvmsg function receives a message and stores a pointer to the nng_msg for that message in msgp.

+
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
+has no messages available to receive. In such a case, it will return NNG_EAGAIN.

 
nng_socket_recv

-
The nng_ctx_send function receives a message asynchronously, using the nng_aio aio, over the context ctx.
-On success, the received message can be retrieved from the aio using the nng_aio_get_msg function.

+
The nng_ctx_send function receives a message asynchronously, using the nng_aio aio, over the context ctx.
+On success, the received message can be retrieved from the aio using the nng_aio_get_msg function.

 

 

   
@@ -389,7 +389,7 @@ Failure to do so will leak the memory.

 

 
This is the preferred function to use for receiving data on a context. While it does require a few extra
 steps on the part of the application, the lowest latencies and highest performance will be achieved by using
-this function instead of nng_ctx_recvmsg.

+this function instead of nng_ctx_recvmsg.

 

 
Context Options

 
int nng_ctx_get_bool(nng_ctx ctx, const char *opt, bool *valp);
@@ -414,7 +414,7 @@ are available for contexts, whether they can be read or written, and the appropr
 
These examples show building blocks for a concurrent service based on contexts.

 
Example 1: Context Echo Server

 
The following program fragment demonstrates the use of contexts to implement
-a concurrent REP service that simply echos messages back
+a concurrent REP service that simply echos messages back
 to the sender.

 
struct echo_context {
     nng_ctx ctx;
@@ -452,8 +452,8 @@ echo(void *arg)
 

 
Example 2: Starting the Echo Service

 
Given the above fragment, the following example shows setting up the service.
-It assumes that the socket has already been
-created and any transports set up as well with functions such as nng_dial or nng_listen.

+It assumes that the socket has already been
+created and any transports set up as well with functions such as nng_dial or nng_listen.

 

 #define CONCURRENCY 1024
 
-- 
cgit v1.2.3-70-g09d2