* master:
  go/zodb/fs1/index: Don't rely on []byte being pickled as string

As https://github.com/kisielk/og-rek/pull/57 maybe shows []byte was
pickling as string only unintentionally and that might change.

We are already explicitly checking for string in corresponding index
load place:

	https://lab.nexedi.com/kirr/neo/blob/2dba8607/go/zodb/storage/fs1/index.go#L282

so it is better we also explicitly save the bits as string.

If we don't and https://github.com/kisielk/og-rek/pull/57 gets accepted,
tests will fail:

	--- FAIL: TestIndexSaveLoad (0.00s)
	    index_test.go:176: index load: /tmp/t-index893650059/458967662/1.fs.index: pickle @6: invalid oidPrefix: type []uint8
	Traceback (most recent call last):
	  File "./py/indexcmp", line 41, in <module>
	    main()
	  File "./py/indexcmp", line 29, in main
	    d2 = fsIndex.load(path2)
	  File "/home/kirr/src/wendelin/z/ZODB/src/ZODB/fsIndex.py", line 138, in load
	    data[ensure_bytes(k)] = fsBucket().fromString(ensure_bytes(v))
	  File "/home/kirr/src/wendelin/z/ZODB/src/ZODB/fsIndex.py", line 71, in ensure_bytes
	    return s.encode('ascii') if not isinstance(s, bytes) else s
	AttributeError: 'bytearray' object has no attribute 'encode'
	--- FAIL: TestIndexSaveToPy (0.04s)
	    index_test.go:218: zodb/py read/compare index: exit status 1

* master:
  go/zodb/btree: New package to work with ZODB BTrees (draft)
  go/zodb: DB - application-level handle to database (very draft)
  go/zodb: Connection: Allow applications to tune live-cache eviction policy
  go/zodb: Implement Connection
  go/zodb/internal/weak: New package to handle weak references
  go/zodb: PyStateful persistency support
  go/zodb: pydata: Factor out class extraction logic into xpyclass
  go/zodb: Persistent - the base type to implement IPersistent objects
  go/zodb: IPersistent + Connection stub
  go/zodb: pkgdoc: Add section overviewing storage drivers
  go/zodb: pkgdoc: Put zodbtools reference into "Miscellaneous" section
  go/zodb: pkgdoc: "Operations" -> "Storage layer"
  go/zodb: pkgdoc: Stress that objects can reference each other in the database
  go/zodb: Pkgdoc cosmetics
  go/zodb: Provide invalid Oid value
  go/zodb: OpenOptions: Document that NoCache disables prefetch
  go/transaction: New package to deal with transactions (very draft)

Provide minimal support for BTrees.LOBTree Get for now.

DB represents a handle to database at application level and contains pool
of connections. DB.Open opens database connection. The connection will be
automatically put back into DB pool for future reuse after corresponding
transaction is complete. DB thus provides service to maintain live objects
cache and reuse live objects from transaction to transaction.

Note that it is possible to have several DB handles to the same database.
This might be useful if application accesses distinctly different sets of
objects in different transactions and knows beforehand which set it will be
next time. Then, to avoid huge cache misses, it makes sense to keep DB
handles opened for every possible case of application access.

TODO handle invalidations.

For example Wendelin.core wcfs will need to keep some types of objects
(e.g. BigFile index) always in RAM for efficiency.

Provide corresponding interface that application could use to install
such live-cache eviction decision-making tuning.

Connection represents an application-level view of a ZODB database.
It has groups of in-RAM application-level objects associated with it.
The objects are isolated from both changes in further database
transactions and from changes to in-RAM objects in other connections.

Connection, as objects group manager, is responsible for handling
object -> object database references. For this to work it keeps

	{} oid -> obj

dict and uses it to find already loaded object when another object
persistently references particular oid. Since it related pydata handling
of persistent references is correspondingly implemented in this patch.

The dict must keep weak references on objects. The following text
explains the rationale:

	if Connection keeps strong link to obj, just
	obj.PDeactivate will not fully release obj if there are no
	references to it from other objects:

	     - deactivate will release obj state (ok)
	     - but there will be still reference from connection `oid -> obj` map to this object,
	       which means the object won't be garbage-collected.

	-> we can solve it by using "weak" pointers in the map.

	NOTE we cannot use regular map and arbitrarily manually "gc" entries
	there periodically: since for an obj we don't know whether other
	objects are referencing it, we can't just remove obj's oid from
	the map - if we do so and there are other live objects that
	reference obj, user code can still reach obj via those
	references. On the other hand, if another, not yet loaded, object
	also references obj and gets loaded, traversing reference from
	that loaded object will load second copy of obj, thus breaking 1
	object in db <-> 1 live object invariant:

	     A  →  B  →  C
	     ↓           |
	     D <--------- - - -> D2 (wrong)

	- A activate
	- D activate
	- B activate
	- D gc, A still keeps link on D
	- C activate -> it needs to get to D, but D was removed from objtab
	  -> new D2 is wrongly created

	that's why we have to depend on Go's GC to know whether there are
	still live references left or not. And that in turn means finalizers
	and thus weak references.

	some link on the subject:
	https://groups.google.com/forum/#!topic/golang-nuts/PYWxjT2v6ps

We will need weak references to handle {} oid -> obj inside zodb.Connection .

In Go world they often say that weak references are not needed at all.
Please see however the next patch for detailed rationale for why weak
references (finalizers and cooperation from Go's GC in other words) are
_required_ in that case.

As promised in 354e0e51 (go/zodb: Persistent - the base type to
implement IPersistent objects) add support to persistency machinery to
set object state from python pickles serialized by ZODB/py.

Persistent references are not yet handled.

As promised add some very minimal persistent tests.

Currently we handle many ways ZODB could serialize a Python class in
PyData.ClassName. Since we'll be using this functionality in other
places soon - extract it into dedicated function.

Since will be also frequently using

	class.__module__ + "." + class.__name__

don't inline it in ClassName and instead put it into pyclassPath() right
away.

Add the base type, that types which want to implement persistency
could embed, and this way inherit persistent functionality. For example

	type MyObject struct {
		Persistent
		...
	}

	type myObjectState MyObject

	func (o *myObjectState) DropState() { ... }
	func (o *myObjectState) SetState(state *mem.Buf) error { ... }

Here state management methods (DropState and SetState) will be
automatically used by persistency machinery on activation and
deactivation.

For this to work MyObject class has to be registered to ZODB

	func init() {
		t := reflect.TypeOf
		zodb.RegisterClass("mymodule.MyObject", t(MyObject{}), t(myObjectState))
	}

and new instances of MyObject has to be created via zodb.NewPersistent:

	obj := zodb.NewPersistent(reflect.TypeOf(MyObject{}), jar).(*MyObject)

SetState corresponds to __setstate__ in Python. However in Go version it
is explicitly separated from class's public API - as it is the contract
between a class and persistency machinery, not between the class and its
user. Notice that SetState takes raw buffer as its argument. In the
following patch we'll add SetState cousing (PySetState) that will be
taking unpickled objects as the state - exactly how __setstate__
operates in Python. Classes will be able to choose whether to accept
state as raw bytes or as a python object.

The activation/deactivation is implemented via reference counting.

Tests are pending (for PySetState).

Add to ZODB/go IPersistent - the interface that is used to represent
in-RAM application-level objects that are mirroring objects in database.

The interface is modelled after Python's IPersistent

	https://github.com/zopefoundation/ZODB/blob/3.10.7-4-gb8d7a8567/src/persistent/interfaces.py#L22

but is not exactly equal to it. In particular we support concurrent
access to an object from multiple goroutines simultaneously.

Due to concurrency support there is no STICKY state, because STICKY is
used in CPython version to temporarily pin object in RAM briefly and is
not safe to use from multiple threads there. Correspondingly the
semantic of PActivate is a bit different from _p_activate - in Go, after
an object has been activated, it is guaranteed that it will remain
present in RAM until it is explicitly deactivated by user.

Please see details of the activation protocol in IPersistent
documentation.

ZODB/py uses interface (IDataManager) for a persistent-object's jar, but
in Go I decided, at least for now, to go without explicit interface at
that level. For this reason a concrete type - Connection - will be used,
and so its stub is also introduced in the patch, since IPersistent wants
to return the connection via PJar.

We already have the functionality, just add an overview on how to
implement drivers and use the most common ones.

There will be many text added to pkgdoc with new sections and
per-section footnotes, and this way it is better to use a dedicated
section for references instead of global footnote whose context might
become unclear.

As we are going to add another - "Application layer" to zodb package,
turn previous text overviewing IStorage & friends into "Storage layer"
section.

We are too used to have this for granted with ZODB, but this property of
object databases is not generally universally available in other databases.

- change "types, interfaces and errors" to API in the header.
- it is not only data model, but also API that is tried to be reasonable
  compatible with ZODB/py.
- an article before "the" transaction is better.