add hg and python

1 files changed, 69 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/api/refcounting.tex b/sys/src/cmd/python/Doc/api/refcounting.tex
new file mode 100644
index 000000000..077543b85
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/refcounting.tex
@@ -0,0 +1,69 @@
+\chapter{Reference Counting \label{countingRefs}}
+
+
+The macros in this section are used for managing reference counts
+of Python objects.
+
+
+\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
+  Increment the reference count for object \var{o}.  The object must
+  not be \NULL; if you aren't sure that it isn't \NULL, use
+  \cfunction{Py_XINCREF()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
+  Increment the reference count for object \var{o}.  The object may be
+  \NULL, in which case the macro has no effect.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
+  Decrement the reference count for object \var{o}.  The object must
+  not be \NULL; if you aren't sure that it isn't \NULL, use
+  \cfunction{Py_XDECREF()}.  If the reference count reaches zero, the
+  object's type's deallocation function (which must not be \NULL) is
+  invoked.
+
+  \warning{The deallocation function can cause arbitrary Python code
+  to be invoked (e.g. when a class instance with a \method{__del__()}
+  method is deallocated).  While exceptions in such code are not
+  propagated, the executed code has free access to all Python global
+  variables.  This means that any object that is reachable from a
+  global variable should be in a consistent state before
+  \cfunction{Py_DECREF()} is invoked.  For example, code to delete an
+  object from a list should copy a reference to the deleted object in
+  a temporary variable, update the list data structure, and then call
+  \cfunction{Py_DECREF()} for the temporary variable.}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
+  Decrement the reference count for object \var{o}.  The object may be
+  \NULL, in which case the macro has no effect; otherwise the effect
+  is the same as for \cfunction{Py_DECREF()}, and the same warning
+  applies.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_CLEAR}{PyObject *o}
+  Decrement the reference count for object \var{o}.  The object may be
+  \NULL, in which case the macro has no effect; otherwise the effect
+  is the same as for \cfunction{Py_DECREF()}, except that the argument
+  is also set to \NULL.  The warning for \cfunction{Py_DECREF()} does
+  not apply with respect to the object passed because the macro
+  carefully uses a temporary variable and sets the argument to \NULL
+  before decrementing its reference count.
+
+  It is a good idea to use this macro whenever decrementing the value
+  of a variable that might be traversed during garbage collection.
+
+\versionadded{2.4}
+\end{cfuncdesc}
+
+
+The following functions are for runtime dynamic embedding of Python:
+\cfunction{Py_IncRef(PyObject *o)}, \cfunction{Py_DecRef(PyObject *o)}.
+They are simply exported function versions of \cfunction{Py_XINCREF()} and 
+\cfunction{Py_XDECREF()}, respectively.
+
+The following functions or macros are only for use within the
+interpreter core: \cfunction{_Py_Dealloc()},
+\cfunction{_Py_ForgetReference()}, \cfunction{_Py_NewReference()}, as
+well as the global variable \cdata{_Py_RefTotal}.