From fd06aba05381055ab56e1ec81d56055b66462f0b Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Thu, 26 Apr 2018 15:36:13 -0700
Subject: fixes #375 integer types are error prone

This change converts the various integer types like nng_socket
in the public API to opaque structures that are passed by value.
Basically we just wrap the integer ID.  This "hack" give us strong
type checks by the compiler (yay!), at the expense of not being able
to directly use these as numbers (so comparisions for example don't
work, and neither does initialization to zero using the normal
method.

Comparison of disassembly output shows that at least with the optimizer
enabled there is no difference in the compiler output between using
a structure or an integral value.
---
 docs/man/nng_ctx.5.adoc | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

(limited to 'docs/man/nng_ctx.5.adoc')

diff --git a/docs/man/nng_ctx.5.adoc b/docs/man/nng_ctx.5.adoc
index 4fcac571..98402738 100644
--- a/docs/man/nng_ctx.5.adoc
+++ b/docs/man/nng_ctx.5.adoc
@@ -19,7 +19,7 @@ nng_ctx - protocol context
 ----
 #include <nng/nng.h>
 
-typedef uint32_t nng_ctx
+typedef struct nng_ctx_s nng_ctx
 ----
 
 == DESCRIPTION
@@ -38,6 +38,11 @@ of any sent request, a timer to retry the request on failure, and so forth.
 A separate context on the same socket can have similar data, but corresponding
 to a completely different request.
 
+IMPORTANT: The `nng_ctx` structure is always passed by value (both
+for input parameters and return values), and should be treated opaquely.
+Passing structures this way ensures gives the compiler a chance to perform
+accurate type checks in functions passing values of this type.
+
 All contexts share the same socket, and so some options, as well as the
 underlying transport details, will be common to all contexts on that socket.
 
-- 
cgit v1.2.3-70-g09d2

