The only update comes from

b@8c9698d6

Rerun `go generate` for this package. Updates come due to updated
`stringer`. zproto-marshal.go stays the same.

When trying to regenerate zproto-marshal.go on a fresh go workspace I
got:

    (neo) (z-dev) (g.env) kirr@deco:~/src/neo/src/lab.nexedi.com/kirr/neo/go/neo/proto$ go generate
    typecheck: ../../zodb/zodb.go:174:2: could not import lab.nexedi.com/kirr/go123/mem (can't find import: "lab.nexedi.com/kirr/go123/mem")
    exit status 1
    proto.go:57: running "sh": exit status 1

Digging around a bit this turned out to be due to that
importer.Default() is using packages in only binary installed form:

    https://github.com/golang/go/issues/19334#issuecomment-283430322
    https://github.com/golang/go/issues/11415

Fix it by using "source" importer which always looks at sources.

(zproto-marshal.go stays unchanged after `go generate` rerun)

So that Go1.13 and golang.org/x/xerrors understand the wrapping:
https://blog.golang.org/go1.13-errors

Preserve Cause for compatibility with github.com/pkg/errors.

This allows to use proper btree.Node type - not just zodb.IPersistent -
in places which expects a tree node.

More comments, typos, ...

If cache control changes, all objects needs to go through new cache
control as what was e.g. pinned before could be in other class
from the point of view of new cache control.

Tests pending...

We already have LiveCacheControl and policy to keep object state in live
cache. However that state is currently kept only until the object is
present in the cache, and the object is there currently only until there
are live pointers to the object from anywhere. If all such pointers go
away, LiveCache currently discards the object.

Add a way (PCachePinObject) to tell live cache that it must retain an
object even if there are no other pointers to it. This is needed for
Wendelin.core which semantically relies on some objects to be present in
live cache, even if in ghost state, for propagating ZODB invalidations
into OS pagecache:

https://lab.nexedi.com/kirr/wendelin.core/blob/000bf16359/wcfs/wcfs.go#L245

For symmetry add a way (PCacheDropObject) to tell live cache that it
must not retain an object. This makes sense for objects that are read in
large only once to avoid needlessly evicting all other objects while
making the room for what won't be soon used again.

For completeness add also a way (PCacheDropState) to tell live cache
that the state of this object should not be cached. This can make sense
even for objects that are pinned: for example Wendelin.core pins ZBlk
objects to rely on volatile metadata it attaches to them, but have to
drop ZBlk state that was loaded from database: that state is propagated
to be cached in OS pagecache, and keeping it also in ZODB live cache
would just waste RAM.

Finally add test to cover LiveCache/LiveCacheControl functionality in
detail.

We are going to rework LiveCache to support both retaining objects in
cache even though if all pointers to them went away (currently such
objects disappear from cache), and to tell the cache that such and such
object should not be cached at all, e.g. not to evict all other objects
on one-time large reads.

This will be done by LiveCacheControl giving cache policy classification
for an object. Prepare for that and change

	WantEvict(obj) -> bool

to

	PCacheClassify(obj) PCachePolicy

which can give more information to LiveCache about how to handle an
object.

This is only a preparatory patch as there is neither no new
functionality nor fixes here.

We already have "testing connection" functionality in common place (was
named tPersistentDB -> now tConnection). However the functionality to
"setup and use testing database" was inside TestPersistentDB only.

Since we are going to add more tests, factor that functionality out of
TestPersistentDB into shared infrastructure that could be reused in
between tests (-> tDB).

It was printing oid instead of obj.

Provide functions to:

- set cache element
- iterate through all elements

LiveCache organization will be changed in the following patch, and it is
better to keep the knowledge about its internal structure localized.

For ZODB we always open database at storage level. Thus `zodb.Open(zurl)`
is relevant. At application level we open database creating DB from
IStorage and using DB.Open() .

Today LastTid is ambiguous: does it return locally cached last transaction ID,
or it performs round-trip to server to get more uptodate view of what has been
last committed? As the result of this ambiguity some drivers (e.g. FileStorage,
ZEO) return cached view, while other drivers (upcoming NEO, living on t branch)
was doing the full round-trip.

There are also situations where whether or not LastTid performs syncing to
server affects semantics: for example if there are two ERP5 nodes and one
node commits something into ZODB and conveys the fact that something has been
committed via another channel, the second ERP5 node should have a reliable way
to observe committed data. But currently there is no such way: on next DB.Open,
even with at=0 meaning "use latest transaction" and with opt.NoSync=false,
DB.Open uses storage.LastTid() as a way to sync and oops - for some drivers it
won't result in real synchronization and thus opened connection could
potentially have older view with not yet latest data.

To fix this ambiguity require drivers to provide Sync functionality only. That
should return ID of last transaction committed to storage data as observed from
some time _afterwards_ Sync call was made. In other words for particular
client-server case, Sync cannot return cached view of storage and has to
perform round-trip to the server.

At IStorage level we provide two entry points: Sync, to perform syncing, and
Head that returns database head (last transaction ID) as viewed by local cache
without any synchronization.

Please see changes to IStorageDriver and IStorage interfaces for details.

The rest of the changes are:

- teach zodb.storage (the IStorage implementer) to actually implement Sync/Head.
- adapt zodb.DB to perform Sync for !opt.NoSync case.
- teach FileStorage to do proper syncing instead of returning local cache.
- teach ZEO to perform "lastTransaction" RPC call for syncing instead of
  returning local cache.
- adapt the rest of the tree to interfaces change.

If we use only the rule that we keep last 10 minutes of database
history, and commits come less often than that - e.g. once per 30
minutes, on every new commit we'll be throwing away all δtail data,
which would result on completely throwing away live cache on every
DB.Open .

Add another rule to cover seldom updates spectrum so that we never throw
till empty δtail and keep at least 10 elements in δtail queue. This will
make sure that live cache is preserved even when updates to database are
seldom to come.

Tests pending...

This gives access to raw data stored in ΔTail. We'll need this in the
next commit, as well as going through raw δtail data is also generally
useful.

Add low-level option to resync Connection to another database state with
preserving its live cache.

Wendelin.core needs this for its main ZODB connection because it needs
to carefully propagate ZODB invalidations into file invalidations and
semantically relies on objects staying in ZODB live cache for this to
work correctly:

https://lab.nexedi.com/kirr/wendelin.core/blob/455a54425c/wcfs/wcfs.go#L245

Implement invalidation handling to teach DB to reuse Connections from
connection pool: after connection is returned to the pool on transaction
completion, we can use this connection for next DB.Open(at) request, by
seeing which objects we changed in conn.at..at range and invalidating
those objects in connection live cache.

To know which objects were changed, DB adds watch on its storage and
maintains some history tail (using ΔTail - see previous commit).

Finally add test for both DB and Connection, and also for Persistent,
LiveCache, ... - as all those application-level components are tightly
inter-related.

Add ΔTail - utility class to keep track of history tail of revisional
changes. This will be needed for both DB (to handle invalidations) and
for raw Cache(*). It also might be useful in places outside of zodb/go -
for example WCFS from Wendelin.core uses ΔTail to keep track of which
ZODB revision changed which block of file(+).

Please see ΔTail comments for details.

(*) to check a bit ahead on load to see whether loaded serial is
actually the latest one for ≤ Cache.head, and, if yes, mark
corresponding cache entry as having .head="current" so that the entry
coverage could be extended when Cache.head is extended to cover more
database state instead of loading the same data from the database again.

(+) that's why we have δtail.go.cat-generic, so that third-party
packages could adapt ΔTail to needed types.

We are going to add more options. Adopt "!" prefix as "no" for
something. Make the code flow in ConnOptions more suitable for further
additions without changing formatter for previous option.

DB is a "handle to database". It has to be closed to release its
resources when no longer needed. We don't have to release anything
currently, but that will soon change in a followup patch.

Due to forgotten ... it was not passing prepared argv as argv to
fmt.Errorf, but as a single slice argument. The result was messy, for
example

    persistent_test.go:176: deactivate refcnt < 0: panic error unexpected:
        have: "[t.zodb.MyObject 000000000000000c](%!s(MISSING)): deactivate: refcnt < 0"
        want: "t.zodb.MyObject(000000000000000c): deactivate: refcnt < 0"

Using the occasion add details to deactivate refcnt panic, which
made me to discover this bug.

Seeing all problems helps to understand what is going on, compared to
e.g. if it complains only about .jar being wrong.

Persistent.refcnt is int, %s prints it as e.g.

	%!s(int=1)

-> use %d.

We are going to use this function in other tests too.

We were not actually checking for it and it is hard to check correctly
since .loading is transient.

Add new `zodb watch` command that is both demonstration of just added
ZODB Watch API (see previous patch), and could be useful for a ZODB
database administration / monitoring.

See zodbtools/watch.go for description.

Add initial draft for IStorage-level watch API and implemention:

- Notifier goes away;
- Add Watcher interface instead with AddWatch/DelWatch calls. See
  Watcher documentation for details.
- IStorage wrapper now subscribes to driver events, retranslate them
  to users and handles Add/Del watch subscription requests.

XXX Raw cache becomes temporarily disabled, until it is fixed to handle invalidations.
XXX Tests pending.

storage is a wrapper that turns IStorageDriver into IStorage. It will
have some logic around almost all IStorageDriver methods. So don't
automatically inherit driver methods not to miss some.

It is already not only open code there, and we are going to add more
storage wrapping functionality into storage (IStorage wrapper over
IStorageDriver). Storage.go thus seems to be a better name.

This continues 4d2c8b1d (go/zodb: Require drivers to provide
notifications for database change events) and a6580062 (go/zodb: Require
drivers to provide at₀ on open) and reworks watchq to receive not only
commit events, but also errors from watcher in storage driver.

Similarly to zodb (632c9798 "go/zodb: storageURL -> zurl")

This are equivalents of PersistentMapping and PersistentList in ZODB/py.
PersistentMapping is usually used as root ZODB object in Zope/ERP5/...

At least we should be able to load and save them now.
Tests pending...

zurl is more handy and is also used in zodbtools which have help on it
(`zodb help zurl`).

BTrees.Length.Length is used in many places in ERP5. At least we should
be able to load and save it now.

Tests pending.

This functions invoke visit callback on every BTree node they traverse.

Wendelin.core needs this to retrieve serials of not only looked up ZBlk
object, but also of every BTree nodes on the path to it.

go/zodb/btree: Bucket.Get: Don't get ctx argument and just require that the bucket must be already activated

It was scheduled to be so as described in removed TODO.

It is either BTree or Bucket.