From aa1801a463e711c19b09b9be34bf76b18fda126c Mon Sep 17 00:00:00 2001 From: Tor Andersson Date: Wed, 29 May 2013 14:40:48 +0200 Subject: Add some documentation about naming and reference counting schemes. --- doc/naming.txt | 30 ++++++++++++++++++++++++++++++ doc/overview.txt | 2 +- doc/refcount.txt | 17 +++++++++++++++++ 3 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 doc/naming.txt create mode 100644 doc/refcount.txt diff --git a/doc/naming.txt b/doc/naming.txt new file mode 100644 index 00000000..6c641c33 --- /dev/null +++ b/doc/naming.txt @@ -0,0 +1,30 @@ +Functions should be named according to one of the following schemes: + + verb_noun + verb_noun_with_noun + + noun_attribute + get_noun_attribute -- when the 'noun_attribute' name conflicts with a type + set_noun_attribute + +Prefixes are mandatory for exported functions, macros, enums, globals and types. + + fz for common code + pdf, xps, etc., for interpreter specific code + +Prefixes are optional (but encouraged) for private functions and types. + +Avoid using 'get' as this is a meaningless and redundant filler word. + +These words are reserved for reference counting schemes: + + new, find, load, open, keep -- return objects that you are responsible for freeing. + + drop, free, close -- relinquish ownership of the object passed in. + +When searching for an object or value, the name used depends on whether +returning the value is passing ownership: + + lookup -- return a value or borrowed pointer + + find -- return an object that the caller is responsible for freeing diff --git a/doc/overview.txt b/doc/overview.txt index a0074b77..2d4e25d7 100644 --- a/doc/overview.txt +++ b/doc/overview.txt @@ -225,7 +225,7 @@ multi-threaded operations run smoothly: document was. This does not mean that the device can only ever be used from one thread, though in many cases this is the simplest structure overall. - + So, how does a multi-threaded example differ from a non-multithreaded one? diff --git a/doc/refcount.txt b/doc/refcount.txt new file mode 100644 index 00000000..e575142a --- /dev/null +++ b/doc/refcount.txt @@ -0,0 +1,17 @@ +Reference counting uses special words in functions to make it easy to remember +and follow the rules. + +Words that take ownership: new, find, load, open, keep. + +Words that release ownership: drop, free, close. + +If an object is returned by a function with one of the special words that take +ownership, you are responsible for freeing it by calling "drop" or "free", or +"close" before you return. You may pass ownership of an owned object by return +it only if you name the function using one of the special words. + +Any objects returned by functions that do not have any of these special words, +are borrowed and have a limited life time. Do not hold on to them past the +duration of the current function, or stow them away inside structs. If you need +to keep the object for longer than that, you have to either "keep" it or make +your own copy. -- cgit v1.2.3