kris/boringssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Clarify "reference" and fix typo.

Browse Source 
It was pointed out that "a reference" to C++ programmers means something
very different from what we intend.

Change-Id: I508196f8e3427ea71439c7871eae9b735a4fa5ca
Reviewed-on: https://boringssl-review.googlesource.com/31544
Reviewed-by: Adam Langley <agl@google.com>
This commit is contained in:
David Benjamin 2018-09-04 18:46:31 -05:00 committed by Adam Langley
parent 8cd61f710b
commit 8e09d90142
1 changed files with 14 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
API-CONVENTIONS.md
View File

@ -182,9 +182,14 @@ used freely without special cleanup conventions.
When working with allocated objects, it is important to think about *ownership* When working with allocated objects, it is important to think about *ownership*
of each object, or what code is responsible for releasing it. This matches the of each object, or what code is responsible for releasing it. This matches the
corresponding notion in higher-level languages like C++ and Rust. Ownership corresponding notion in higher-level languages like C++ and Rust.
applies to both uniquely-owned types and reference-counted types. For the
latter, ownership means the code is responsible for releasing one reference. Ownership applies to both uniquely-owned types and reference-counted types. For
the latter, ownership means the code is responsible for releasing one
reference. Note a *reference* in BoringSSL refers to an increment (and eventual
decrement) of an object's reference count, not `T&` in C++. Thus, to "take a
reference" means to increment the reference count and take ownership of
decrementing it.
As BoringSSL's APIs are primarily in C, ownership and lifetime obligations are As BoringSSL's APIs are primarily in C, ownership and lifetime obligations are
not rigorously annotated in the type signatures or checked at compile-time. not rigorously annotated in the type signatures or checked at compile-time.
@ -217,12 +222,12 @@ sooner on state change in the parent object.
If documented to output a *newly-allocated* object or a *reference* or *copy* of If documented to output a *newly-allocated* object or a *reference* or *copy* of
one, the caller is responsible for releasing the object when it is done. one, the caller is responsible for releasing the object when it is done.
By convention, functions named `get0` return non-owning pointers. Functions name By convention, functions named `get0` return non-owning pointers. Functions
`new` or `get1` return owning pointers. Functions named `set0` take ownership of named `new` or `get1` return owning pointers. Functions named `set0` take
arguments. Functions named `set1` do not. They typically take a reference or ownership of arguments. Functions named `set1` do not. They typically take a
make a copy internally. These names originally referred to the effect on a reference or make a copy internally. These names originally referred to the
reference count, but the convention applies equally to non-reference-counted effect on a reference count, but the convention applies equally to
types. non-reference-counted types.
API documentation may also describe more complex obligations. For instance, an API documentation may also describe more complex obligations. For instance, an
object may borrow a pointer for longer than the duration of a single function object may borrow a pointer for longer than the duration of a single function