From 4fee35a32c600d603034b6eb077a55899513ba4d Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 3 Dec 2017 15:07:46 +0200 Subject: [PATCH] docs/glossary: Describe the callee-owned tuple concept. --- docs/library/uselect.rst | 4 ++-- docs/reference/glossary.rst | 23 +++++++++++++++++++++++ 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/library/uselect.rst b/docs/library/uselect.rst index 211b2a4a80..f88ab7d1d9 100644 --- a/docs/library/uselect.rst +++ b/docs/library/uselect.rst @@ -78,8 +78,8 @@ Methods .. method:: poll.ipoll(timeout=-1, flags=0) - Like :meth:`poll.poll`, but instead returns an iterator which yields - `callee-owned tuples`. This function provides efficient, allocation-free + Like :meth:`poll.poll`, but instead returns an iterator which yields a + `callee-owned tuple`. This function provides an efficient, allocation-free way to poll on streams. If *flags* is 1, one-shot behavior for events is employed: streams for diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 4cd3d84cc5..b6153550c0 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -15,6 +15,29 @@ Glossary may also refer to "boardless" ports like :term:`Unix port `). + callee-owned tuple + A tuple returned by some builtin function/method, containing data + which is valid for a limited time, usually until next call to the + same function (or a group of related functions). After next call, + data in the tuple may be changed. This leads to the following + restriction on the usage of callee-owned tuples - references to + them cannot be stored. The only valid operation is extracting + values from them (including making a copy). Callee-owned tuples + is a MicroPython-specific construct (not available in the general + Python language), introduced for memory allocation optimization. + The idea is that callee-owned tuple is allocated once and stored + on the callee side. Subsequent calls don't require allocation, + allowing to return multiple values when allocation is not possible + (e.g. in interrupt context) or not desirable (because allocation + inherently leads to memory fragmentation). Note that callee-owned + tuples are effectively mutable tuples, making an exception to + Python's rule that tuples are immutable. (It may be interesting + why tuples were used for such a purpose then, instead of mutable + lists - the reason for that is that lists are mutable from user + application side too, so a user could do things to a callee-owned + list which the callee doesn't expect and could lead to problems; + a tuple is protected from this.) + CPython CPython is the reference implementation of Python programming language, and the most well-known one, which most of the people