qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acon...@apache.org
Subject qpid-proton git commit: NO-JIRA: Add explanatory comment on PN_HANDLE to object.h
Date Wed, 13 Apr 2016 14:53:10 GMT
Repository: qpid-proton
Updated Branches:
  refs/heads/master 3ea4287d4 -> b47234bf5


NO-JIRA: Add explanatory comment on PN_HANDLE to object.h

Several people have been confused by its usage, added an explanation.


Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/b47234bf
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/b47234bf
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/b47234bf

Branch: refs/heads/master
Commit: b47234bf539f2be0c5db82071bf5851cb81c3174
Parents: 3ea4287
Author: Alan Conway <aconway@redhat.com>
Authored: Wed Apr 13 10:47:39 2016 -0400
Committer: Alan Conway <aconway@redhat.com>
Committed: Wed Apr 13 10:52:32 2016 -0400

----------------------------------------------------------------------
 proton-c/include/proton/object.h | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b47234bf/proton-c/include/proton/object.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/object.h b/proton-c/include/proton/object.h
index 464aff3..827aa77 100644
--- a/proton-c/include/proton/object.h
+++ b/proton-c/include/proton/object.h
@@ -266,6 +266,23 @@ PN_EXTERN void *pn_iterator_next(pn_iterator_t *iterator);
 
 #define PN_LEGCTX ((pn_handle_t) 0)
 
+/**
+   PN_HANDLE is a trick to define a unique identifier by using the address of a static variable.
+   You MUST NOT use it in a .h file, since it must be defined uniquely in one compilation
unit.
+   Your .h file can provide access to the handle (if needed) via a function. For example:
+
+       /// my_thing.h
+       pn_handle_t get_my_thing(void);
+
+       /// my_thing.c
+       PN_HANDLE(MY_THING);
+       pn_handle_t get_my_thing(void) { return MY_THING; }
+
+   Note that the name "MY_THING" is not exported and is not required to be
+   unique except in the .c file. The linker will guarantee that the *address* of
+   MY_THING, as returned by get_my_thing() *is* unique across the entire linked
+   executable.
+ */
 #define PN_HANDLE(name) \
   static const char _PN_HANDLE_ ## name = 0; \
   static const pn_handle_t name = ((pn_handle_t) &_PN_HANDLE_ ## name);


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message