SYNOPSIS
cc [flags] files -lnng [libraries]
DESCRIPTION
The nng(7) library provides a common messaging framework intended to solve common communication problems in distributed applications.
It provides a C language API.
Common Functions
The following common functions exist in libnng.
allocate memory |
|
create and start a dialer |
|
free memory |
|
return an error description |
Socket Functions
The following functions operate on sockets.
close a socket |
|
close all open sockets |
|
create and start a dialer |
|
get a socket option |
|
create and start a listener |
|
receive data |
|
send data |
|
set a socket option |
Message Functions
Applications desiring to use the richest part of libnng will want to use the message API, where a message structure is passed between functions. This API provides the most power support for zero-copy.
Messages are divided into a header and body, where the body generally carries user-payload and the header carries protocol specific header information. Most applications will only interact with the body.
allocate a message |
|
return the message body |
|
free a message |
|
return the message header |
|
return the message header length |
|
return the message body length |
|
reallocate a message |
|
receive a message |
|
send a message |
Asynchronous Operations
Most applications will interact with nng synchronously; that is that functions such as nng_send() will block the calling thread until the operation has completed.
| Synchronous operations which send messages may return before the message has actually been received, or even transmitted. Instead, These functions return as soon as the message was successfully queued for delivery. |
Asynchronous operations behave differently. These operations are initiated by the calling thread, but control returns immediately to the calling thread. When the operation is subsequently completed (regardless of whether this was successful or not), then a user supplied function ("callback") is executed.
A context structure, called an aio, is allocated and associated for each asynchronous operation. Only a single asynchronous operation may be associated with an aio at any time.
The following functions are used in the asynchronous model:
allocate asynchronous I/O context |
|
cancel asynchronous I/O operation |
|
free asynchronous I/O context |
|
get message from an asynchronous receive |
|
return result from asynchronous operation |
|
stop asynchronous I/O operation |
|
wait for an asynchronous I/O operation |
|
set message for an asynchronous send |
|
set timeout for an asynchronous send |
|
receive a message asynchronously |
|
send a message asynchronously |
Protocols
The following functions are used to construct a socket with a specific protocol:
open a bus socket |
|
open a pair socket |
|
open a pub socket |
|
open a rep socket |
|
open a req socket |
|
open a respondent socket |
|
open a sub socket |
|
open a surveyor socket |
Transports
The following functions are used to register a transport for use.
register inproc transport |
|
register IPC transport |
|
register TCP transport |
|
register ZeroTier transport |
SEE ALSO
COPYRIGHT
Copyright 2017 Garrett D’Amore
Copyright 2017 Capitar IT Group BV
This document is supplied under the terms of the MIT License.