Man page - libnng(3)

Packages contains this manual

Manual

LIBNNG

NAME
SYNOPSIS
DESCRIPTION
Common Functions
Socket Functions
Connection Management
Message Handling Functions
Message Header Handling
Asynchronous Operations
Protocols
Transports
Protocol Contexts
Devices, Relays
Statistics
URL Object
Logging Support
Supplemental API
Byte Streams
HTTP Support
Common HTTP Functions
HTTP Client Functions
HTTP Server Functions
TLS Configuration Objects
SEE ALSO

NAME

libnng - nanomsg next generation library

SYNOPSIS

cc [ flags ] files -lnng [ libraries ]

DESCRIPTION

NNG 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 .

Image grohtml-456352-1.png

Socket Functions

The following functions operate on sockets.

Image grohtml-456352-2.png

Connection Management

The following functions are used with either listeners, or dialers. Listeners accept incoming connection requests, and dialers make them.

Image grohtml-456352-3.png

Message Handling 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.

Image grohtml-456352-4.png

Message Header Handling

Tip

Few applications will need these functions, as message headers are only used to carry protocol-specific content. However, applications which use raw mode may need to access the header of messages.

Image grohtml-456352-5.png

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.

Note

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 is executed.

A context structure, an nng_aio, is allocated and associated with each asynchronous operation. Only a single asynchronous operation may be associated with an nng_aio at any time.

The following functions are used in the asynchronous model:

Image grohtml-456352-6.png

Protocols

The following functions are used to construct a socket with a specific protocol:

Image grohtml-456352-7.png

Transports

The following functions are used to register a transport for use. This is no longer necessary, and applications should not call these functions anymore.

Image grohtml-456352-8.png

Protocol Contexts

The following functions are useful to separate the protocol processing from a socket object, into a separate context. This can allow multiple contexts to be created on a single socket for concurrent applications.

Image grohtml-456352-9.png

Devices, Relays

The following function family is used to create forwarders or relayers that route messages from one socket to another.

Image grohtml-456352-10.png

Statistics

The following functions provide access to statistics which can be used to observe program behaviors and as an aid in troubleshooting.

Image grohtml-456352-11.png

URL Object

Common functionality is supplied for parsing and handling universal resource locators (URLS).

Image grohtml-456352-12.png

Logging Support

Common functionality for message logging.

Image grohtml-456352-13.png

Supplemental API

These supplemental functions are not intrinsic to building network applications with NNG , but they are made available as a convenience to aid in creating portable applications.

Image grohtml-456352-14.png

Byte Streams

These functions are available for use with byte streams. They are considered low-level, for uses where the higher level functions using Scalability Protocols are inappropriate.

Byte streams, represented by nng_stream objects, correspond to underlying connections such as TCP connections or named pipes. They are created by either nng_stream_dialer or nng_stream_listener objects.

Image grohtml-456352-15.png

HTTP Support

The library may be configured with support for HTTP, and this will be the case if WebSocket support is configured as well. In this case, it is possible to access functionality to support the creation of HTTP (and HTTP/S if TLS support is present) servers and clients.

Common HTTP Functions

The following functions are used to work with HTTP requests, responses, and connections.

Image grohtml-456352-16.png

HTTP Client Functions

These functions are intended for use with HTTP client applications.

Image grohtml-456352-17.png

HTTP Server Functions

These functions are intended for use with HTTP server applications.

Image grohtml-456352-18.png

TLS Configuration Objects

The following functions are used to manipulate transport layer security (TLS) configuration objects. Most of these functions will not be used even by TLS applications.

Note

These functions will only be present if the library has been built with TLS support.

Image grohtml-456352-19.png

SEE ALSO

nng_compat(3compat), nng(7)