This will be needed in the following patches to know how to inject
zconn_at or zconn resync functionality into particular ZODB version.

- mention in comments that _ZBigFileH not only proxies changes from
  virtmem -> ZODB, but also the other way: virtmem <- ZODB.
- refresh comments, fix typo.

- Provide brief top-level overview + refresh loadblk/storeblk/release comments.
- Add `typedef struct bigfile_ops bigfile_ops` that we usually add for all structs.

It is valid to compare a Page and a VMA only if they belong to the same
fileh.

-> into vma_page_infilerange().

We will soon need to use this functionality from several places.

Start preparing vma early, not after the call to mem_valloc.
This codeflow will be more convenient when we add mmap-through-wcfs codepath.

We are soon going to use this functionality from several places.

The place to perform the mmap is changed slightly because vma_mmap_page
deduces prot from page->state and for that we have to finish preparing
page->state first.

Freed Page structs must be in PAGE_EMPTY state.

The code sequence of

        list_del(&page->lru);
        bzero(page, sizeof(*page)); /* just in case */
        free(page);

was open-coded several times.

This is needed so that e.g. a Python class implemented in C or Cython
(cdef class) could inherit from PyBigFile.

Don't put _bigfile.h into separate include/ directory, and keep it along
main .c file, similarly to how pygolang is organized.

Provide package-level documentation that gives brief overview of what
this package does. Split internal notes into separate comment.

Starting from 5755a6b3 (Basic setup.py / Makefile to build/install/sdist
stuff + bigfile.so skeleton) and 35eb95c2 (bigfile: Python wrapper
around virtual memory subsystem) we were using Plan9 C extensions[1] for
simple inheritance. Those extensions are supported by GCC with
-fplan9-extensions option. However that option is supported only for C,
while for C++ it does not work at all with error produced by the compiler
on Plan9 syntax.

Soon we'll need to add another extension - written in C++ - to
wendelin.core . This extension will be providing client side of WCFS and
integrating that with virtmem. In that extension we'll need to use
_bigfile data structures - in particular we'll need to use PyBigFile and
extend it with another `cdef class` children written in Cython/C++.

This patch prepares for that: first stop using Plan9 C extensions in
_bigfile py module data structures and adapt the code correspondingly.
In the next patch we'll move those data structures into an .h file.

We don't drop -fplan9-extensions from setup.py, because Plan9-style
inheritance continues to be used internally by virtmem - e.g. in
ram_shmfs.c and friends.

A bit pity to drop that good stuff, but given that we'll need to use C++
for WCFS client for other good stuff provided by pygolang[2], it is a
reasonable compromise.

[1] http://9p.io/sys/doc/comp.html  "Extensions" section
[2] https://pypi.org/project/pygolang

It was from long-ago marked as "XXX move to common place".

I noticed this while working on WCFS: if file blocks topology change,
the invalidation process is not working correctly. It is also not
correct with respect to live cache pressure.

Add FIXME in the code and test for live cache pressure.

kirr/wendelin.core@5a4562fc
kirr/wendelin.core@48eb692f
kirr/wendelin.core@d1a579b2
kirr/wendelin.core@69c94fbc

For ZBlk0 this is trivial, but for ZBlk1 it may seem that we could avoid
changing ZBlk object itself and mark only pointed-to ZData object as
changed. However that would be not correct to do if we consider
invalidations.

Noticed while working on WCFS.

Add package-level documentation to

  - bigfile/file_zodb.py,
  - bigarray/array_zodb.py, and
  - lib/zodb.py

The most interesting read is file_zodb.py .

Slightly improve documenation for functions in a couple of places.

Improving documentation was long overdue and it is improved only slightly by this commit.

We already keep FileStorage test database on /tmp/ and NEO itself (via
neo.tests.functional.NEOCluster) also keeps test data on tmpfs. However
test database for ZEO was created in current directory and was wearing
out SSD unnecessarily.

FIXME zeo_forker currently does not provide API to keep all server files
in particular place. This way server conf and log are still emitted in
current directory, but at least we move data.fs away. Since conf and log
are uniquely named, e.g. server-<ΧΧΧ>.conf and tmpYYY.log, and it was
only that Data.fs was named non-uniquely, by moving Data.fs into unique
per-server place, this also helps with-ZEO tests to execute correctly in
parallel with `tox -p`.

Else it won't compile with C++. This needs my patch to CCAN to work.
Patch description and problem details are here:

http://git.ozlabs.org/?p=ccan;a=commitdiff;h=39b46a02b719

We are going to add C++ parts to wendelin.core soon.
Mark all current functionality with `extern "C"` as a preparatory step.

There was an XXX of whether fileh_open should be a BigFile method or
global function. However if it would be a global function it will need
to anyway accept file parameter to indicate which file is opened, and
that in turn suggests that it should be a file method. Remove XXX.

try/finally was used in a couple of places to save/restore default ZBlk
format setting. Move the restore part close to save with the help of
defer.

For tests this makes sure that if one test fails, it won't make following
tests fail just because the next test will fail trying to lock test database.

For regular code (demo_zbigarray.py) this is also a good thing to do -
to always close the database irregardless of whether an exception was
raised before program reached end of main.

Pygolang becomes regular - not test only - dependency. Being regular
dependency is currently required only by demo_zbigarray.py, but it will
be also used in upcoming wcfs, so adding pygolang into wendelin.core
dependencies aligns with the plan.

dbclose now uses defer almost everywhere - there are still few places in
tests, where one test function is opening/closing test database multiple
times - those were not (yet ?) converted.

Instead of

	raises(Exception, 'code')

do

	with raises(Exception):
		code

This removes lots of warnings, similar to below example:

	bigfile/tests/test_basic.py::test_basic
	  /home/kirr/src/wendelin/wendelin.core/bigfile/tests/test_basic.py:79: PytestDeprecationWarning: raises(..., 'code(as_a_string)') is deprecated, use the context manager form or use `exec()` directly

	  See https://docs.pytest.org/en/latest/deprecations.html#raises-warns-exec
	    raises(ROAttributeError, "f.blksize = 1") # RO attribute

-> into CHECK_MRU and CHECK_DIRTY.

Besides improving signal/noise ratio in tests, it also gives more
details by printing full lists when things are found to be different
from expected.

The undef defined in that function were placed in next function going
after it which does not define any macro.

It was already said there that allocated page is not associated with
fileh. However the code is doing more - it does not add the page to
ram->lru_list and (obviously) to fileh->dirty_pages lists.

Document that explicitly.

It should release resources associated with RAM. Make it call .ram_close
from RAM ops. Add corresponding .ram_close to ram_shmfs. This fixes
SHMFS_RAM->prefix leak.

test_ram is low-level test that tests RAM pages allocation/mmapping.
As allocated pages are not integrated with virtmem (not added to any
file mapping and RAM->lru_list) the Page structs have to be explicitly
freed. Fixes e.g.

	Direct leak of 80 byte(s) in 1 object(s) allocated from:
	    #0 0x7ff29af46518 in calloc (/usr/lib/x86_64-linux-gnu/libasan.so.5+0xe9518)
	    #1 0x56131dc22289 in zalloc include/wendelin/utils.h:67
	    #2 0x56131dc225d6 in ramh_alloc_page bigfile/tests/../ram.c:41
	    #3 0x56131dc2a19e in main bigfile/tests/test_ram.c:130
	    #4 0x7ff29ac9f09a in __libc_start_main ../csu/libc-start.c:308

Else on-heap allocated RAM object is leaked. Fixes e.g. the following
error on ASAN:

	Direct leak of 56 byte(s) in 1 object(s) allocated from:
	    #0 0x7fc9ef390518 in calloc (/usr/lib/x86_64-linux-gnu/libasan.so.5+0xe9518)
	    #1 0x555ca792f309 in zalloc include/wendelin/utils.h:67
	    #2 0x555ca7935f9a in ram_limited_new bigfile/tests/../../t/t_utils.c:35
	    #3 0x555ca793a0ba in test_file_access_synthetic bigfile/tests/test_virtmem.c:292
	    #4 0x555ca7967bc4 in main bigfile/tests/test_virtmem.c:1121
	    #5 0x7fc9ef0e909a in __libc_start_main ../csu/libc-start.c:308

Only one place that was using ram_new was missing to call ram_close in
the end.

For failing case compiler-rt support was added in 2014 - 5 years ago
(see links in removed code).

-> Use .[test] to refer to them.
https://stackoverflow.com/a/41398850/9456786