Commit 3684d164 authored by Kirill Smelkov's avatar Kirill Smelkov

bigfile/py: Provide package-level documentation

Provide package-level documentation that gives brief overview of what
this package does. Split internal notes into separate comment.
parent bf44905b
...@@ -17,15 +17,28 @@ ...@@ -17,15 +17,28 @@
* *
* See COPYING file for full licensing terms. * See COPYING file for full licensing terms.
* See https://www.nexedi.com/licensing for rationale and options. * See https://www.nexedi.com/licensing for rationale and options.
*/
/* Package _bigfile provides Python bindings to virtmem.
*
* - `BigFile` is base class that allows implementing BigFile backends in Python.
* Users can inherit from BigFile, implement loadblk/storeblk and this way
* provide access to data managed from Python to virtmem subsystem.
* - `BigFileH` represents virtmem file handle for opened BigFile.
* It can be mmap'ed and provides writeout control.
* - `VMA` represents mmap'ed part of a BigFileH.
* It provides buffer/memoryview interface for data access.
*/
/* _bigfile organization
* *
* ~~~~~~~~ * NOTE on refcounting - who holds who:
* *
* TODO big picture module description * vma -> fileh -> file
* - what maps to what, briefly * ^ |
* +---------+
* fileh->mmaps (kind of weak)
* *
* VMA with a buffer/memoryview interface
* BigFileH with mmap (-> vma) and writeout control
* BigFile base class (to allow implementing BigFile backends in python)
* *
* NOTE virtmem/bigfile functions release/reacquire GIL (see virt_lock()) - * NOTE virtmem/bigfile functions release/reacquire GIL (see virt_lock()) -
* thus functions that use them cannot assume they run mutually exclusive to * thus functions that use them cannot assume they run mutually exclusive to
...@@ -141,16 +154,6 @@ struct PyBigFile { ...@@ -141,16 +154,6 @@ struct PyBigFile {
typedef struct PyBigFile PyBigFile; typedef struct PyBigFile PyBigFile;
/* NOTE on refcounting: who holds who
*
*
* vma -> fileh -> file
* ^ |
* +---------+
* fileh->mmaps (kind of weak)
*/
/* like PyObject_New, but fully initializes instance (e.g. calls type ->tp_new) */ /* like PyObject_New, but fully initializes instance (e.g. calls type ->tp_new) */
#define PyType_New(type, typeobj, args) \ #define PyType_New(type, typeobj, args) \
( (type *)PyObject_CallObject((PyObject *)(typeobj), args) ) ( (type *)PyObject_CallObject((PyObject *)(typeobj), args) )
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment