diff options
| -rw-r--r-- | docs/libnng.adoc | 172 |
1 files changed, 172 insertions, 0 deletions
diff --git a/docs/libnng.adoc b/docs/libnng.adoc new file mode 100644 index 00000000..108cbad6 --- /dev/null +++ b/docs/libnng.adoc @@ -0,0 +1,172 @@ +libnng(3) +========= +:doctype: manpage +:manmanual: nng +:mansource: nng +:icons: font +:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \ + Copyright 2017 Capitar IT Group BV <info@capitar.com> \ + This software 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 +---- +libnng - nanomsg next generation library + +SYNOPSIS +-------- +*cc* ['flags'] 'files' *-lnng* ['libraries'] + + +DESCRIPTION +----------- + +The <<nng.adoc#,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_. + +[cols="1,4"] +|=== +|<<nng_alloc.adoc#,nng_alloc(3)>>|allocate memory +|<<nng_dial.adoc#,nng_dial(3)>>|create and start a dialer +|<<nng_free.adoc#,nng_free(3)>>|free memory +|<<nng_strerror.adoc#,nng_strerror(3)>>|return an error description +|=== + +Socket Functions +~~~~~~~~~~~~~~~~ + +The following functions operate on sockets. + +[cols="1,4"] +|=== +|<<nng_close.adoc#,nng_close(3)>>|close a socket +|<<nng_closeall.adoc#,nng_closeall(3)>>|close all open sockets +|<<nng_dial.adoc#,nng_dial(3)>>|create and start a dialer +|<<nng_getopt.adoc#,nng_getopt(3)>>|get a socket option +|<<nng_listen.adoc#,nng_listen(3)>>|create and start a listener +|<<nng_protocol.adoc#,nng_protocol(3)>>|return the protocol number for socket +|<<nng_peer.adoc#,nng_peer(3)>>|return peer protocol number for socket +|<<nng_recv.adoc#,nng_recv(3)>>|receive data +|<<nng_send.adoc#,nng_send(3)>>|send data +|<<nng_setopt.adoc#,nng_setopt(3)>>|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. + +[cols="1,4"] +|=== +|<<nng_msg_alloc.adoc#,nng_msg_alloc(3)>>|allocate a message +|<<nng_msg_body.adoc#,nng_msg_body(3)>>|return the message body +|<<nng_msg_free.adoc#,nng_msg_free(3)>>|free a message +|<<nng_msg_header.adoc#,nng_msg_header(3)>>|return the message header +|<<nng_msg_header_len.adoc#,nng_msg_header_len(3)>>|return the message header length +|<<nng_msg_len.adoc#,nng_msg_len(3)>>|return the message body length +|<<nng_msg_realloc.adoc#,nng_msg_free(3)>>|reallocate a message +|<<nng_recv_msg.adoc#,nng_recvmsg(3)>>|receive a message +|<<nng_sendmsg.adoc#,nng_sendmsg(3)>>|send a message +|=== + +Asynchronous Operations +~~~~~~~~~~~~~~~~~~~~~~~ + +Most applications will interact with _nng_ synchronously; that is that +functions such as <<nng_send.adoc#,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 +("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: + +[cols="1,4"] +|=== +|<<nng_aio_alloc.adoc#,nng_aio_alloc(3)>>|allocate asynchronous I/O context +|<<nng_aio_cancel.adoc#,nng_aio_cancel(3)>>|cancel asynchronous I/O operation +|<<nng_aio_free.adoc#,nng_aio_free(3)>>|free asynchronous I/O context +|<<nng_aio_get_msg.adoc#,nng_aio_get_msg(3)>>|get message from an asynchronous receive +|<<nng_aio_result.adoc#,nng_aio_result(3)>>|return result from asynchronous operation +|<<nng_aio_stop.adoc#,nng_aio_stop(3)>>|stop asynchronous I/O operation +|<<nng_aio_wait.adoc#,nng_aio_wait(3)>>|wait for an asynchronous I/O operation +|<<nng_aio_set_msg.adoc#,nng_aio_set_msg(3)>>|set message for an asynchronous send +|<<nng_aio_set_timeout.adoc#,nng_aio_set_timeout(3)>>|set timeout for an asynchronous send +|<<nng_recv_aio.adoc#,nng_recv_aio(3)>>|receive a message asynchronously +|<<nng_send_aio.adoc#,nng_send_aio(3)>>|send a message asynchronously +|=== + +Protocols +~~~~~~~~~ + +The following functions are used to construct a socket with a specific +protocol: + +[cols="1,4"] +|=== +| <<nng_bus.adoc#,nng_bus_open(3)>>|open a bus socket +| <<nng_pair.adoc#,nng_pair_open(3)>>|open a pair socket +| <<nng_pub.adoc#,nng_pub_open(3)>>|open a pub socket +| <<nng_rep.adoc#,nng_rep_open(3)>>|open a rep socket +| <<nng_req.adoc#,nng_req_open(3)>>|open a req socket +| <<nng_respondent.adoc#,nng_respondent_open(3)>>|open a respondent socket +| <<nng_sub.adoc#,nng_sub_open(3)>>|open a sub socket +| <<nng_surveyor.adoc#,nng_surveyor_open(3)>>|open a surveyor socket +|=== + +Transports +~~~~~~~~~~ + +The following functions are used to register a transport for use. + +[cols="1,4"] +|=== +| <<nng_inproc.adoc#,nng_inproc_register(3)>>|register inproc transport +| <<nng_ipc.adoc#,nng_ipc_register(3)>>|register IPC transport +| <<nng_tcp.adoc#,nng_tcp_register(3)>>|register TCP transport +| <<nng_zerotier.adoc#,nng_zerotier_register(3)>>|register ZeroTier transport +|=== + +AUTHORS +------- +link:mailto:garrett@damore.org[Garrett D'Amore] + +SEE ALSO +-------- +<<nng.adoc#,nng(7)>> +<<nng_compat.adoc#,nng_compat(3)>> + +COPYRIGHT +--------- + +Copyright 2017 mailto:garrett@damore.org[Garrett D'Amore] + +Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/LICENSE.txt[MIT License]. |