fixes #381 Want comparators for various types

12 files changed, 308 insertions, 2 deletions

diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 8df29861..149dc9f4 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -49,6 +49,7 @@ The following functions operate on sockets.
 |<<nng_recv.3#,nng_recv()>>|receive data
 |<<nng_send.3#,nng_send()>>|send data
 |<<nng_setopt.3#,nng_setopt()>>|set socket option
+|<<nng_socket_id.3#,nng_socket_id()>>|get numeric socket identifier
 |===
 
 === Connection Management
@@ -61,16 +62,19 @@ Listeners accept incoming connection requets, and dialers make them.
 |<<nng_dialer_close.3#,nng_dialer_close()>>|close dialer
 |<<nng_dialer_create.3#,nng_dialer_create()>>|create dialer
 |<<nng_dialer_getopt.3#,nng_dialer_getopt()>>|get dialer option
+|<<nng_dialer_id.3#,nng_dialer_id()>>|get numeric dialer identifier
 |<<nng_dialer_setopt.3#,nng_dialer_setopt()>>|set dialer option
 |<<nng_dialer_start.3#,nng_dialer_start()>>|start dialer
 |<<nng_listen.3#,nng_listen()>>|create and start listener
 |<<nng_listener_close.3#,nng_listener_close()>>|close listener
 |<<nng_listener_create.3#,nng_listener_create()>>|create listener
 |<<nng_listener_getopt.3#,nng_listener_getopt()>>|get listener option
+|<<nng_listener_id.3#,nng_listener_id()>>|get numeric listener identifier
 |<<nng_listener_setopt.3#,nng_listener_setopt()>>|set listener option
 |<<nng_listener_start.3#,nng_listener_start()>>|start listener
 |<<nng_pipe_close.3#,nng_pipe_close()>>|close pipe
 |<<nng_pipe_getopt.3#,nng_pipe_getopt()>>|get pipe option
+|<<nng_pipe_id.3#,nng_pipe_id()>>|get numeric pipe identifier
 |===
 
 === Message Handling Functions
@@ -205,6 +209,7 @@ concurrent applications.
 |===
 |<<nng_ctx_close.3#,nng_ctx_close()>>|close context
 |<<nng_ctx_getopt.3#,nng_ctx_getopt()>>|get context option
+|<<nng_ctx_id.3#,nng_ctx_id()>>|get numeric context identifier
 |<<nng_ctx_open.3#,nng_ctx_open()>>|create context
 |<<nng_ctx_recv.3#,nng_ctx_recv()>>|receive message using context asynchronously
 |<<nng_ctx_send.3#,nng_ctx_send()>>|send message using context asynchronously
diff --git a/docs/man/nng_ctx.5.adoc b/docs/man/nng_ctx.5.adoc
index 98402738..ada117c3 100644
--- a/docs/man/nng_ctx.5.adoc
+++ b/docs/man/nng_ctx.5.adoc
@@ -81,6 +81,12 @@ are in use on the same socket is not supported, and may lead to unpredictable
 behavior.
 These asynchronous methods should not be mixed on the same socket.
 
+[[NNG_CTX_INITIALIZER]]
+=== Initialization
+
+A context may be initialized using the macro `NNG_CTX_INITIALIZER`
+before it is opened, to prevent confusion with valid open contexts.
+
 == EXAMPLE
 
 The following program fragment demonstrates the use of contexts to implement
@@ -91,7 +97,7 @@ to the sender.
 ----
 
 struct echo_context {
-    nng_ctx *ctx;
+    nng_ctx ctx;
     nng_aio *aio;
     enum { INIT, RECV, SEND } state;
 };
@@ -156,6 +162,7 @@ start_echo_service(nng_socket rep_socket)
 <<nng_ctx_close.3#,nng_ctx_close(3)>>,
 <<nng_ctx_open.3#,nng_ctx_open(3)>>,
 <<nng_ctx_getopt.3#,nng_ctx_getopt(3)>>,
+<<nng_ctx_id.3#,nng_ctx_id(3)>>,
 <<nng_ctx_recv.3#,nng_ctx_recv(3)>>,
 <<nng_ctx_send.3#,nng_ctx_send(3)>>,
 <<nng_ctx_setopt.3#,nng_ctx_setopt(3)>>,
diff --git a/docs/man/nng_ctx_id.3.adoc b/docs/man/nng_ctx_id.3.adoc
new file mode 100644
index 00000000..56d9d7bd
--- /dev/null
+++ b/docs/man/nng_ctx_id.3.adoc
@@ -0,0 +1,50 @@
+= nng_ctx_id(3)
+//
+// Copyright 2018 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_ctx_id - return numeric context identifier
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_ctx_id(nng_ctx c);
+----
+
+== DESCRIPTION
+
+The `nng_ctx_id()` function returns a positive identifier for the context _c_,
+if it is valid.
+Otherwise it returns `-1`.
+
+NOTE: A context is considered valid if it was ever opened with
+<<nng_ctx_open.3#,`nng_ctx_open`>> function.
+Contexts that are allocated on the stack or statically should be
+initialized with the macro
+<<nng_ctx.5#NNG_CTX_INITIALIZER,`NNG_CTX_INITIALIZER`>> to ensure that
+they cannot be confused with a valid context before they are opened.
+
+== RETURN VALUES
+
+This function returns the positive value for the context identifier, or
+`-1` if the context is invalid.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_ctx.5#,nng_ctx(5)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_dialer.5.adoc b/docs/man/nng_dialer.5.adoc
index 45c60bc9..3f742c21 100644
--- a/docs/man/nng_dialer.5.adoc
+++ b/docs/man/nng_dialer.5.adoc
@@ -58,12 +58,19 @@ Dialer objects may be destroyed by the
 <<nng_dialer_close.3#,`nng_pipe_close()`>> function.
 They are also closed when their "`owning`" socket is closed.
 
+[[NNG_DIALER_INITIALIZER]]
+=== Initialization
+
+A dialer may be initialized using the macro `NNG_DIALER_INITIALIZER`
+before it is opened, to prevent confusion with valid open dialers.
+
 == SEE ALSO
 
 <<nng_dial.3#,nng_dial(3)>>,
 <<nng_dialer_close.3#,nng_dialer_close(3)>>,
 <<nng_dialer_create.3#,nng_dialer_create(3)>>,
 <<nng_dialer_getopt.3#,nng_dialer_getopt(3)>>,
+<<nng_dialer_id.3#,nng_dialer_id(3)>>,
 <<nng_dialer_setopt.3#,nng_dialer_setopt(3)>>,
 <<nng_dialer_start.3#,nng_dialer_start(3)>>,
 <<nng_listener.5#,nng_listener(5)>>,
diff --git a/docs/man/nng_dialer_id.3.adoc b/docs/man/nng_dialer_id.3.adoc
new file mode 100644
index 00000000..cf8936b5
--- /dev/null
+++ b/docs/man/nng_dialer_id.3.adoc
@@ -0,0 +1,51 @@
+= nng_dialer_id(3)
+//
+// Copyright 2018 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_dialer_id - return numeric dialer identifier
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_dialer_id(nng_dialer d);
+----
+
+== DESCRIPTION
+
+The `nng_dialer_id()` function returns a positive identifier for the dialer _d_,
+if it is valid.
+Otherwise it returns `-1`.
+
+NOTE: A dialer is considered valid if it was ever created with the
+<<nng_dialer_create.3#,`nng_dialer_create`>> or
+<<nng_dial.3#,`nng_dial`>> functions.
+Dialers that are allocated on the stack or statically should be
+initialized with the macro
+<<nng_ctx.5#NNG_DIALER_INITIALIZER,`NNG_DIALER_INITIALIZER`>> to ensure that
+they cannot be confused with a valid dialer before they are created properly.
+
+== RETURN VALUES
+
+This function returns the positive value for the dialer identifier, or
+`-1` if the dialer is invalid.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_dialer.5#,nng_dialer(5)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_listener.5.adoc b/docs/man/nng_listener.5.adoc
index 558eb920..e7187a61 100644
--- a/docs/man/nng_listener.5.adoc
+++ b/docs/man/nng_listener.5.adoc
@@ -55,12 +55,19 @@ Listener objects may be destroyed by the
 <<nng_listener_close.3#,`nng_listener_close()`>> function.
 They are also closed when their "`owning`" socket is closed.
 
+[[NNG_LISTENER_INITIALIZER]]
+=== Initialization
+
+A listener may be initialized using the macro `NNG_LISTENER_INITIALIZER`
+before it is opened, to prevent confusion with valid open listener.
+
 == SEE ALSO
 
 <<nng_listen.3#,nng_listen(3)>>,
 <<nng_listener_close.3#,nng_listener_close(3)>>,
 <<nng_listener_create.3#,nng_listener_create(3)>>,
 <<nng_listener_getopt.3#,nng_listener_getopt(3)>>,
+<<nng_listener_id.3#,nng_listener_id(3)>>,
 <<nng_listener_setopt.3#,nng_listener_setopt(3)>>,
 <<nng_listener_start.3#,nng_listener_start(3)>>,
 <<nng_dialer.5#,nng_dialer(5)>>,
diff --git a/docs/man/nng_listener_id.3.adoc b/docs/man/nng_listener_id.3.adoc
new file mode 100644
index 00000000..44404e14
--- /dev/null
+++ b/docs/man/nng_listener_id.3.adoc
@@ -0,0 +1,51 @@
+= nng_listener_id(3)
+//
+// Copyright 2018 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_listener_id - return numeric listener identifier
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_listener_id(nng_listener l);
+----
+
+== DESCRIPTION
+
+The `nng_listener_id()` function returns a positive identifier for the
+listener _l_, if it is valid.
+Otherwise it returns `-1`.
+
+NOTE: A listener is considered valid if it was ever created with the
+<<nng_listener_create.3#,`nng_listener_create`>> or
+<<nng_listen.3#,`nng_listen`>> functions.
+listeners that are allocated on the stack or statically should be
+initialized with the macro
+<<nng_ctx.5#NNG_LISTENER_INITIALIZER,`NNG_LISTENER_INITIALIZER`>> to ensure that
+they cannot be confused with a valid listener before they are created properly.
+
+== RETURN VALUES
+
+This function returns the positive value for the listener identifier, or
+`-1` if the listener is invalid.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_listener.5#,nng_listener(5)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_pipe.5.adoc b/docs/man/nng_pipe.5.adoc
index 39247fbd..a7423884 100644
--- a/docs/man/nng_pipe.5.adoc
+++ b/docs/man/nng_pipe.5.adoc
@@ -51,11 +51,25 @@ Pipe objects may be destroyed by the
 They are also closed when their "`owning`" dialer or listener is closed,
 or when the remote peer closes the underlying connection.
 
+[[NNG_PIPE_INITIALIZER]]
+=== Initialization
+
+A pipe may be initialized using the macro `NNG_PIPE_INITIALIZER`
+before it is opened, to prevent confusion with valid open pipes.
+
+For example:
+
+[source, c]
+----
+nng_pipe p = NNG_PIPE_INITIALIZER;
+----
+
 == SEE ALSO
 
 <<nng_msg_get_pipe.3#,nng_msg_get_pipe(3)>>,
 <<nng_pipe_close.3#,nng_pipe_close(3)>>,
 <<nng_pipe_getopt.3#,nng_pipe_getopt(3)>>,
+<<nng_pipe_id.3#,nng_pipe_id(3)>>,
 <<nng_dialer.5#,nng_dialer(5)>>,
 <<nng_listener.5#,nng_listener(5)>>,
 <<nng_options.5#,nng_options(5)>>,
diff --git a/docs/man/nng_pipe_close.3.adoc b/docs/man/nng_pipe_close.3.adoc
index 598e143a..2128caec 100644
--- a/docs/man/nng_pipe_close.3.adoc
+++ b/docs/man/nng_pipe_close.3.adoc
@@ -19,7 +19,7 @@ nng_pipe_close - close pipe
 ----
 #include <nng/nng.h>
 
-int nng_pipe_close(nng_socket s);
+int nng_pipe_close(nng_pipe p);
 ----
 
 == DESCRIPTION
diff --git a/docs/man/nng_pipe_id.3.adoc b/docs/man/nng_pipe_id.3.adoc
new file mode 100644
index 00000000..b327dac2
--- /dev/null
+++ b/docs/man/nng_pipe_id.3.adoc
@@ -0,0 +1,50 @@
+= nng_pipe_id(3)
+//
+// Copyright 2018 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_pipe_id - return numeric pipe identifier
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_pipe_id(nng_pipe p);
+----
+
+== DESCRIPTION
+
+The `nng_pipe_id()` function returns a positive identifier for the pipe _p_,
+if it is valid.
+Otherwise it returns `-1`.
+
+NOTE: A pipe is considered valid if it was ever opened with
+<<nng_pipe_open.3#,`nng_pipe_open`>> function.
+Pipes that are allocated on the stack or statically should be
+initialized with the macro
+<<nng_pipe.5#NNG_PIPE_INITIALIZER,`NNG_PIPE_INITIALIZER`>> to ensure that
+they cannot be confused with a valid pipe before they are opened.
+
+== RETURN VALUES
+
+This function returns the positive value for the pipe identifier, or
+`-1` if the pipe is invalid.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_pipe.5#,nng_pipe(5)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_socket.5.adoc b/docs/man/nng_socket.5.adoc
index 4711495f..2d8d7256 100644
--- a/docs/man/nng_socket.5.adoc
+++ b/docs/man/nng_socket.5.adoc
@@ -44,12 +44,26 @@ Each `nng_socket` is created by a protocol-specific constructor, such as
 When the socket is no longer needed, it can be closed with
 <<nng_close.3#,`nng_close()`>>.
 
+[[NNG_SOCKET_INITIALIZER]]
+=== Initialization
+
+A socket may be initialized using the macro `NNG_SOCKET_INITIALIZER`
+before it is opened, to prevent confusion with valid open sockets.
+
+For example:
+
+[source, c]
+----
+nng_socket s = NNG_SOCKET_INITIALIZER;
+----
+
 == SEE ALSO
 
 <<libnng.3#,libnng(3)>>,
 <<nng_close.3#,nng_close(3)>>,
 <<nng_getopt.3#,nng_getopt(3)>>,
 <<nng_setopt.3#,nng_setopt(3)>>,
+<<nng_socket_id.3#,nng_socket_id(3)>>,
 <<nng_dialer.5#,nng_dialer(5)>>,
 <<nng_listener.5#,nng_listener(5)>>,
 <<nng_options.5#,nng_options(5)>>,
diff --git a/docs/man/nng_socket_id.3.adoc b/docs/man/nng_socket_id.3.adoc
new file mode 100644
index 00000000..b5acc98b
--- /dev/null
+++ b/docs/man/nng_socket_id.3.adoc
@@ -0,0 +1,50 @@
+= nng_socket_id(3)
+//
+// Copyright 2018 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_socket_id - return numeric socket identifier
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_socket_id(nng_socket s);
+----
+
+== DESCRIPTION
+
+The `nng_socket_id()` function returns a positive identifier for the socket _s_,
+if it is valid.
+Otherwise it returns `-1`.
+
+NOTE: A socket is considered valid if it was ever opened with a protocol
+constructor, such as the <<nng_req0_open.3#,`nng_req0_open`>> function.
+Sockets that are allocated on the stack or statically should be
+initialized with the macro
+<<nng_socket.5#NNG_SOCKET_INITIALIZER,`NNG_SOCKET_INITIALIZER`>> to ensure that
+they cannot be confused with a valid socket before they are opened.
+
+== RETURN VALUES
+
+This function returns the positive value for the socket identifier, or
+`-1` if the socket is invalid.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_socket.5#,nng_socket(5)>>,
+<<nng.7#,nng(7)>>