.

go/zodb/connection.go

@@ -23,13 +23,14 @@ import (
 	"lab.nexedi.com/kirr/neo/go/zodb/internal/weak"
 )
 
-// Connection represents an isolated application-level view of ZODB database. XXX + live application objects.
+// Connection represents application-level view of a ZODB database.
 //
 // The view is represented by IPersistent objects associated with the connection.
+// Connection changes are private and are isolated from changes in other Connections.
 //
-// The view is representing state of ZODB objects as of `at` transaction.
+// The view corresponds to particular database state and is thus isolated from
+// further database transactions.
 //
-// Connection changes are private and are isolated from changes in other Connections.
 //
 // Connection is safe to access from multiple goroutines simultaneously.
 //
@@ -110,7 +111,6 @@ type LiveCacheControl interface {
 	WantEvict(obj IPersistent) (ok bool)
 }
 
-
 // ----------------------------------------
 
 // wrongClassError is the error cause returned when ZODB object's class is not what was expected.

go/zodb/db.go

+// Copyright (c) 2001, 2002 Zope Foundation and Contributors.
+// All Rights Reserved.
+//
+// Copyright (C) 2018  Nexedi SA and Contributors.
+//                     Kirill Smelkov <kirr@nexedi.com>
+//
+// This software is subject to the provisions of the Zope Public License,
+// Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+// THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+// WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+// FOR A PARTICULAR PURPOSE
+
+package zodb
+// application-level database connection.
+
+// DB represents a handle to database at application level and contains pool
+// of connections. If application opens connection via DB.Open, 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.
+//
+// DB is safe to access from multiple goroutines simultaneously.
+type DB struct {
+}

go/zodb/db_test.go

+// Copyright (c) 2001, 2002 Zope Foundation and Contributors.
+// All Rights Reserved.
+//
+// Copyright (C) 2018  Nexedi SA and Contributors.
+//                     Kirill Smelkov <kirr@nexedi.com>
+//
+// This software is subject to the provisions of the Zope Public License,
+// Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+// THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+// WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+// FOR A PARTICULAR PURPOSE
+
+package zodb
+
+// TODO

go/zodb/persistent.go

@@ -440,6 +440,8 @@ type Broken struct {
 	state *mem.Buf
 }
 
+// XXX register (Broken, brokenState) ?
+
 type brokenState Broken // hide state methods from public API
 
 func (b *brokenState) DropState() {

go/zodb/zodb.go

@@ -111,7 +111,7 @@
 // application objects isolated for modifications is represented by Connection.
 // Connection is also sometimes called a "jar" in ZODB terminology.
 //
-// DB represents a handle to database at application level and contains a pool
+// DB represents a handle to database at application level and contains pool
 // of connections. If application opens connection via DB.Open, the connection
 // will be automatically put back into DB pool for future reuse after
 // corresponding transaction is complete. DB thus provides service to maintain