zodb

type Broken struct {
	Persistent
	// contains filtered or unexported fields
}

type Cache struct {
	// contains filtered or unexported fields
}

type Committer interface {
}

type ConnOptions struct {
	At     Tid  // if !0, open Connection bound to `at` view of database; not latest.
	NoSync bool // don't sync with storage to get its last tid.

	// don't put connection back into DB pool after transaction ends.
	//
	// This is low-level option that allows to inspect/use connection's
	// LiveCache after transaction finishes, and to manually resync the
	// connection onto another database view. See Connection.Resync for
	// details.
	NoPool bool
}

type Connection struct {
	// contains filtered or unexported fields
}

type DB struct {
	// contains filtered or unexported fields
}

type DBOptions struct {
	// CacheControl, if !nil, is set as default live cache control for
	// newly created connections.
	CacheControl LiveCacheControl
}

type DataInfo struct {
	Oid  Oid
	Tid  Tid    // changed by this transaction
	Data []byte // new object data; nil if object becomes deleted

	// DataTidHint is optional hint from a storage that the same data was
	// already originally committed in earlier transaction, for example in
	// case of undo. It is 0 if there is no such hint.
	//
	// Storages are not obliged to provide this hint, and in particular it
	// is valid for a storage to always return this as zero.
	//
	// In ZODB/py world this originates from
	// https://github.com/zopefoundation/ZODB/commit/2b0c9aa4.
	DataTidHint Tid
}

type DriverOpener func(ctx context.Context, u *url.URL, opt *DriverOptions) (_ IStorageDriver, at0 Tid, _ error)

type DriverOptions struct {
	ReadOnly bool // whether to open storage as read-only

	// Channel where storage events have to be delivered.
	//
	// Watchq can be nil to ignore such events. However if Watchq != nil, the events
	// have to be consumed or else the storage driver will misbehave - e.g.
	// it can get out of sync with the on-disk database file, or deadlock
	// on any user-called operation.
	//
	// The storage driver closes !nil Watchq when the driver is closed.
	//
	// The storage driver will send only and all events in (at₀, +∞] range,
	// where at₀ is at returned by driver open.
	//
	// The storage driver will stop sending events after call to Close.
	// In particular the following example is valid and safe from deadlock:
	//
	//	watchq := make(chan zodb.Event)
	//	stor, at0, err := zodb.OpenDriver(..., &DriverOptions{Watchq: watchq})
	//	defer stor.Close()
	//
	//	for {
	//		select {
	//		case <-ctx.Done():
	//			return ctx.Err()
	//
	//		case <-watchq:
	//			...
	//		}
	//	}
	Watchq chan<- Event
}

type Event interface {
	// contains filtered or unexported methods
}

type EventCommit struct {
	Tid     Tid   // ID of committed transaction
	Changev []Oid // ID of objects changed by committed transaction
}

type EventError struct {
	Err error
}

type Ghostable interface {
	// DropState should discard in-RAM object state.
	//
	// It is called by persistency machinery only on non-ghost objects,
	// i.e. when the objects has its in-RAM state.
	DropState()
}

type IDataIterator interface {
	// NextData yields information about next storage data record.
	// returned data stays valid until next call to NextData().
	// end of iteration is indicated with io.EOF
	NextData(ctx context.Context) (*DataInfo, error)
}

type IPersistent interface {
	PJar() *Connection // Connection this in-RAM object is part of.
	POid() Oid         // object ID in the database.

	// object serial in the database as of particular Connection (PJar) view.
	// InvalidTid if not yet loaded.
	PSerial() Tid

	// PActivate brings object to live state.
	//
	// It requests to persistency layer that in-RAM object data to be present.
	// If object state was not in RAM - it is loaded from the database.
	//
	// On successful return the object data is either the same as in the
	// database or, if this data was previously modified by user of
	// object's jar, that modified data.
	//
	// Object data must be accessed only after corresponding PActivate
	// call, which marks that object's data as being in use.
	PActivate(ctx context.Context) error

	// PDeactivate indicates that corresponding PActivate caller finished access to object's data.
	//
	// As PActivate makes sure object's data is present in-RAM, PDeactivate
	// tells persistency layer that this data is no longer used by
	// corresponding PActivate caller.
	//
	// Note that it is valid to have several concurrent uses of object
	// data, each protected with corresponding PActivate/PDeactivate pair:
	// as long as there is still any PActivate not yet compensated with
	// corresponding PDeactivate, object data will assuredly stay alive in RAM.
	//
	// Besides exotic cases, the caller thus must not use object's data
	// after PDeactivate call.
	PDeactivate()

	// PInvalidate requests in-RAM object data to be discarded.
	//
	// Irregardless of whether in-RAM object data is the same as in the
	// database, or it was modified, that in-RAM data must be forgotten.
	//
	// PInvalidate must not be called while there is any in-progress
	// object's data use (PActivate till PDeactivate).
	//
	// In practice this means that:
	//
	//	- application must make sure to finish all objects accesses
	//	  before transaction boundary: at transaction boundary - either
	//	  at abort or commit, the persistency layer will sync to
	//	  database and process invalidations.
	//
	//	- if PInvalidate is explicitly called by application, the
	//	  application must care to make sure it does not access the
	//	  object data simultaneously.
	PInvalidate()
	// contains filtered or unexported methods
}

type IStorage interface {
	// same as in IStorageDriver
	URL() string
	Close() error
	Loader
	Iterator

	// Sync syncs to storage and updates current view of it.
	//
	// After Sync, Head is guaranteed to give ID of last transaction
	// committed to storage data as observed from some time _afterwards_
	// Sync call was made. In particular for client-server case, Sync
	// cannot retain cached view of storage and has to perform round-trip
	// to the server.
	Sync(context.Context) error

	// Head returns ID of last committed transaction.
	//
	// Returned head is ID of last committed transaction as observed from
	// some time _before_ Head call returns. In particular for
	// client-sever case, Head can return cached view of storage that was
	// learned some time ago.
	//
	// Head is ↑=.
	//
	// Head is 0 if no transactions have been committed yet.
	//
	// Use Sync to synchronize with the storage.
	Head() Tid

	// additional to IStorageDriver
	Prefetcher
	Watcher
}

type IStorageDriver interface {
	// URL returns URL of how the storage was opened
	URL() string

	// Close closes storage
	Close() error

	// Sync syncs to storage and returns ID of last committed transaction.
	//
	// Returned head is ID of last transaction committed to storage data as
	// observed from some time _afterwards_ Sync call was made. In particular
	// for client-server case, Sync cannot return cached view of storage
	// and has to perform round-trip to the server.
	//
	// Head is ↑=.
	//
	// Head is 0 if no transactions have been committed yet.
	Sync(ctx context.Context) (head Tid, _ error)

	Loader
	Iterator
}

type ITxnIterator interface {
	// NextTxn yields information about next database transaction:
	// 1. transaction metadata, and
	// 2. iterator over transaction's data records.
	// transaction metadata stays valid until next call to NextTxn().
	// end of iteration is indicated with io.EOF
	NextTxn(ctx context.Context) (*TxnInfo, IDataIterator, error)
}

type Iterator interface {
	// Iterate creates iterator to iterate storage in [tidMin, tidMax] range.
	//
	// Iterate does not return any error. If there was error when setting
	// iteration up - it will be returned on first NextTxn call.
	//
	// TODO allow iteration both ways (forward & backward)
	Iterate(ctx context.Context, tidMin, tidMax Tid) ITxnIterator
}

type List struct {
	Persistent

	// XXX it is not possible to embed slice - see Map for similar issue and more details.
	Data []interface{}
}

type LiveCache struct {
	sync.Mutex
	// contains filtered or unexported fields
}

type LiveCacheControl interface {
	// PCacheClassify is called to classify an object and returns live
	// cache policy that should be used for this object.
	PCacheClassify(obj IPersistent) PCachePolicy
}

type Loader interface {
	// Load loads object data addressed by xid from database.
	//
	// Returned are:
	//
	//	- if there is data to load: buf is non-empty, serial indicates
	//	  transaction which matched xid criteria and err=nil.
	//
	//	  caller must not modify buf memory.
	//
	// otherwise buf=nil, serial=0 and err is *OpError with err.Err
	// describing the error cause:
	//
	//	- *NoObjectError if there is no such object in database at all,
	//	- *NoDataError   if object exists in database but there is no
	//	                 its data matching xid,
	//	- some other error indicating e.g. IO problem.
	//
	//
	// NOTE 1: ZODB/py provides 2 entrypoints in IStorage for loading:
	// loadSerial and loadBefore but in ZODB/go we have only Load which is
	// a bit different from both:
	//
	//	- Load loads object data for object at database state specified by xid.At
	//	- loadBefore loads object data for object at database state previous to xid.At
	//	  it is thus equivalent to Load(..., xid.At-1)
	//	- loadSerial loads object data from revision exactly modified
	//	  by transaction with tid = xid.At.
	//	  it is thus equivalent to Load(..., xid.At) with followup
	//	  check that returned serial is exactly xid.At(*)
	//
	// (*) loadSerial is used only in a few places in ZODB/py - mostly in
	//     conflict resolution code where plain Load semantic - without
	//     checking object was particularly modified at that revision - would
	//     suffice.
	//
	// NOTE 2: in ZODB/py loadBefore, in addition to serial, also returns
	// serial_next, which constraints storage implementations unnecessarily
	// and is used only in client cache.
	//
	// In ZODB/go Cache shows that it is possible to build efficient client
	// cache without serial_next returned from Load. For this reason in ZODB/go
	// Load specification comes without specifying serial_next return.
	Load(ctx context.Context, xid Xid) (buf *mem.Buf, serial Tid, err error)
}

type Map struct {
	Persistent

	// XXX it is not possible to embed map. And even if we embed a map via
	// another type = map, then it is not possible to use indexing and
	// range over Map. -> just provide access to the map as .Data .
	Data map[interface{}]interface{}
}

type NoDataError struct {
	Oid Oid

	// DeletedAt explains object state wrt used search criteria:
	// - 0:  object was not created at time of searched xid.At
	// - !0: object was deleted by transaction with tid=DeletedAt
	DeletedAt Tid
}

type NoObjectError struct {
	Oid Oid
}

type ObjectState int

type Oid uint64

type OpError struct {
	URL  string      // URL of the storage
	Op   string      // operation that failed
	Args interface{} // operation arguments, if any
	Err  error       // actual error that occurred during the operation
}

type OpenOptions struct {
	ReadOnly bool // whether to open storage as read-only
	NoCache  bool // don't use cache for read/write operations; prefetch will be noop
}

type PCachePolicy int

type Persistent struct {
	// contains filtered or unexported fields
}

type Prefetcher interface {
	// Prefetch prefetches object addressed by xid.
	//
	// If data is not yet in cache loading for it is started in the background.
	// Prefetch is not blocking operation and does not wait for loading, if any was
	// started, to complete.
	//
	// Prefetch does not return any error.
	// Prefetch is noop if storage was opened with NoCache option.
	Prefetch(ctx context.Context, xid Xid)
}

type PyData []byte

type PyStateful interface {
	// PyGetState should return state of the in-RAM object as Python data.
	//
	// It is analog of __getstate__() in Python.
	//
	// It is called by persistency machinery only on non-ghost objects,
	// i.e. when the object has its in-RAM state.
	PyGetState() interface{}

	// PySetState should set state of the in-RAM object from Python data.
	//
	// It is analog of __setstate__() in Python.
	//
	// It is called by persistency machinery only on ghost objects, i.e.
	// when the objects does not yet have its in-RAM state.
	//
	// The error returned does not need to have object/setstate prefix -
	// persistency machinery is adding such prefix automatically.
	PySetState(pystate interface{}) error
}

type Stateful interface {
	// GetState should return state of the in-RAM object as raw data.
	//
	// It is called by persistency machinery only on non-ghost objects,
	// i.e. when the object has its in-RAM state.
	//
	// GetState should return a new buffer reference.
	GetState() *mem.Buf

	// SetState should set state of the in-RAM object from raw data.
	//
	// It is called by persistency machinery only on ghost objects, i.e.
	// when the objects does not yet have its in-RAM state.
	//
	// state ownership is not passed to SetState, so if state needs to be
	// retained after SetState returns it needs to be incref'ed.
	//
	// The error returned does not need to have object/setstate prefix -
	// persistent machinery is adding such prefix automatically.
	SetState(state *mem.Buf) error
}

type Tid uint64

type TimeStamp struct {
	time.Time
}

type TxnInfo struct {
	Tid         Tid
	Status      TxnStatus
	User        []byte
	Description []byte

	// additional information about transaction. ZODB/py usually puts py
	// dict here but it can be arbitrary raw bytes.
	Extension []byte
}

type TxnStatus byte

type Watcher interface {
	// AddWatch registers watchq to be notified of database changes.
	//
	// Whenever a new transaction is committed into the database,
	// corresponding event will be sent to watchq.
	//
	// It is guaranteed that events are coming with ↑ .Tid .
	//
	// It will be only and all events in (at₀, +∞] range, that will be
	// sent, where at₀ is database head that was current when AddWatch call
	// was made.
	//
	// Once registered, watchq must be read until it is closed or until
	// DelWatch call. Not doing so will stuck whole storage.
	//
	// Registered watchq are closed when the database storage is closed.
	//
	// It is safe to add watch to a closed database storage.
	//
	// AddWatch must be used only once for a particular watchq channel.
	AddWatch(watchq chan<- Event) (at0 Tid)

	// DelWatch unregisters watchq from being notified of database changes.
	//
	// After DelWatch call completes, no new events will be sent to watchq.
	// It is safe to call DelWatch without simultaneously reading watchq.
	// In particular the following example is valid:
	//
	//	at0 := stor.AddWatch(watchq)
	//	defer stor.DelWatch(watchq)
	//
	//	for {
	//		select {
	//		case <-ctx.Done():
	//			return ctx.Err()
	//
	//		case <-watchq:
	//			...
	//		}
	//	}
	//
	// DelWatch is noop if watchq was not registered.
	DelWatch(watchq chan<- Event)
}

type Xid struct {
	At  Tid
	Oid Oid
}

type ΔRevEntry struct {
	Rev     Tid
	Changev []Oid
}

type ΔTail struct {
	// contains filtered or unexported fields
}