[API-NEXT] doc: userguide: clarify packet reference operation

Message ID 20170215002651.15346-1-bill.fischofer@linaro.org
State New
Headers show

Commit Message

Bill Fischofer Feb. 15, 2017, 12:26 a.m.
Clarify usage information around packet references in cases where
implementations simulate references by returning copies of packets.

Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>

 doc/users-guide/users-guide-packet.adoc | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)



diff --git a/doc/users-guide/users-guide-packet.adoc b/doc/users-guide/users-guide-packet.adoc
index d5f2ff19..44dd4e3e 100644
--- a/doc/users-guide/users-guide-packet.adoc
+++ b/doc/users-guide/users-guide-packet.adoc
@@ -336,9 +336,9 @@  The key characteristic of a static reference is that because there are
 multiple independent handles that refer to the same packet, the caller should
 treat the packet as read only following the creation of a static reference
 until all other references to it are freed. This is because all static
-references are simply aliases of the same packet, so if multiple threads were
-independently manipulating the packet this would lead to unpredictable race
+references are simply aliases of the same packet and associated metadata, so
+if multiple threads were independently manipulating the packet this would lead
+to unpredictable race conditions.
 To assist in determining whether there are other references to a packet, ODP
 provides the API:
@@ -513,7 +513,10 @@  packets as part of any reference creation call. The
 `odp_packet_unshared_len()` API will always provide an authoritative answer to
 the question of how many bytes of a packet may safely be modified in any
 context, so whether or not copies have been performed applications can be
-assured of portability across all conforming ODP implementations.
+assured of portability across all conforming ODP implementations. In addition,
+if a reference call returns a copy of a packet for whatever reason, the
+`odp_packet_has_ref()` API will return 0 to confirm that this is an
+independent packet.
 Note also that a packet may not reference itself, nor may circular reference
 relationships be formed, _e.g.,_ packet A is used as a header for a reference