.

wcfs/zodb.go

@@ -22,13 +22,19 @@ import (
 	"lab.nexedi.com/kirr/neo/go/zodb"
 )
 
-// IPersistent is the interface that every in-RAM object representing any ZODB object implements.
+// IPersistent is the interface that every in-RAM object representing any database object implements.
+//
+// It is based on IPersistent from ZODB/py:
+//
+//	https://github.com/zopefoundation/ZODB/blob/3.10.7-4-gb8d7a8567/src/persistent/interfaces.py#L22
+//
+// but is not exactly equal to it.
 type IPersistent interface {
 	PJar()    *Connection	// Connection this in-RAM object is part of.
 	POid()    zodb.Oid	// object ID in the database.
 
-	// object serial as of database state for particular Connection (PJar).
-	// 0 if not yet loaded (XXX ok?)
+	// object serial in the database as of particular Connection (PJar) view.
+	// 0 (invalid tid) if not yet loaded (XXX ok?)
 	PSerial() zodb.Tid
 
 
@@ -80,8 +86,20 @@ type IPersistent interface {
 	//	  object data simultaneously.
 	PInvalidate()
 
+	// PModify marks in-RAM object state as modified.
+	//
+	// It informs persistency layer that object's data was changed and so
+	// its state needs to be either saved back into database on transaction
+	// commit, or discarded on transaction abort.
+	//
+	// The object must be already activated.
+	//PModify()	TODO
+
+	// XXX probably don't need this.
+	//PState()  ObjectState	// in-RAM object state.
+
 
-	// Object must be stateful for persistency to work
+	// Object must be stateful for persistency to work.
 	// XXX try to move out of IPersistent?
 	Stateful
 }
@@ -96,7 +114,7 @@ const (
 	// no STICKY - we pin objects in RAM with PActivate
 )
 
-// Persistent is common base implementation for in-RAM representation of ZODB objects.
+// Persistent is common base implementation for in-RAM representation of database objects.
 type Persistent struct {
 	jar	*Connection
 	oid	zodb.Oid
@@ -110,7 +128,7 @@ type Persistent struct {
 }
 
 func (obj *Persistent) PJar() *Connection	{ return obj.jar	}
-func (obj *Persistent) POid() zodb.Oid	{ return obj.oid	}
+func (obj *Persistent) POid() zodb.Oid		{ return obj.oid	}
 func (obj *Persistent) PSerial() zodb.Tid	{ return obj.serial	}
 
 // loadState indicates object's load state/result.
@@ -125,7 +143,7 @@ type loadState struct {
 	err   error
 }
 
-// Stateful is the interface describing in-RAM object whose data stat can be
+// Stateful is the interface describing in-RAM object whose data state can be
 // exchanged as raw bytes.
 type Stateful interface {
 	// DropState should discard in-RAM object state.
@@ -134,7 +152,8 @@ type Stateful interface {
 
 	// SetState should set state of the in-RAM object from raw data.
 	//
-	// SetState must incref state buffer, if it needs the buffer to stay dedicated XXX
+	// state ownership is not passed to SetState, so if state needs to be
+	// retained after SetState returns it needs to be incref'ed.
 	SetState(state *mem.Buf) error
 
 	// GetState should return state of the in-RAM object as raw data.
@@ -202,7 +221,7 @@ type Connection struct {
 	// https://groups.google.com/forum/#!topic/golang-nuts/PYWxjT2v6ps
 	//
 	// NOTE2 finalizers don't run on when they are attached to an object in cycle.
-	// Hopefully we don't have cycles with ZBtree/ZBucket	XXX verify this
+	// Hopefully we don't have cycles with ZBTree/ZBucket	XXX verify this
 	objmu  sync.Mutex
 	objtab map[zodb.Oid]*WeakRef	// oid -> WeakRef(IPersistent)