qpid-proton git commit: NO-JIRA: update memory_management.md to clarify that mixing free and refcounts is a Bad Idea.

[ac...@apache.org]

Repository: qpid-proton
Updated Branches:
  refs/heads/master 4e878602d -> e45e96b53


NO-JIRA: update memory_management.md to clarify that mixing free and refcounts is a Bad Idea.


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

Branch: refs/heads/master
Commit: e45e96b53ba949fd51b2c1f810100a2a7da60ab7
Parents: 4e87860
Author: Alan Conway <ac...@redhat.com>
Authored: Wed Aug 19 18:10:21 2015 -0400
Committer: Alan Conway <ac...@redhat.com>
Committed: Wed Aug 19 18:10:21 2015 -0400

----------------------------------------------------------------------
 docs/markdown/memory_management.md | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/e45e96b5/docs/markdown/memory_management.md
----------------------------------------------------------------------
diff --git a/docs/markdown/memory_management.md b/docs/markdown/memory_management.md
index 2441e21..e81318f 100644
--- a/docs/markdown/memory_management.md
+++ b/docs/markdown/memory_management.md
@@ -44,18 +44,19 @@ Proton reference counting in C
 ------------------------------
 
 Internally, the proton C library uses reference counting, and you can
-*optionally* use it in your code. Reminder: if you just want to use proton to
-send and receive AMQP messages *you do not need to know or care about reference
-counting*. The binding library takes care of it, or in C you can call
-`pn_X_free` yourself like a grown-up.
+*optionally* use it in your code. You should choose *either* reference counting
+*or* `pn_X_free` in your code, *not both*. It might work, but it is the sort of
+Bad Idea that might break your code in the future and will hurt your head in the
+present. `pn_X_free` is all you really need to write an AMQP application in C.
 
 However, proton is designed to be embedded and integrated. If you are
 integrating proton with a new programming language, or some other kind of
-framwork, reference counts may be useful. As a rule of thumb, if your target
-language has native reference counting and/or finalizers (aka destructors) then
-reference counts may help (e.g. python, ruby and C++). As a counter-example the
-Go langauge *is* garbage collected but does *not* have finalizers, and the Go
-binding does *not* use reference counts.
+framwork, reference counts may be useful. If your integration target has some
+form of automatic clean-up *and* some way for you to hook into it (finalizers,
+destructors or the like) then reference counts may help (e.g. python, ruby and
+C++). As a counter-example the Go langauge *is* garbage collected but does *not*
+have finalizers, and the Go binding does *not* use reference counts, it is
+written like a "normal" C application with `pn_X_free`.
 
 If you are mixing your own C code with code using a reference-counted proton
 binding (e.g. C++ or python) then you may need to at least be aware of reference


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