Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Z
ZEO
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Analytics
Analytics
CI / CD
Repository
Value Stream
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
nexedi
ZEO
Commits
940a5198
Commit
940a5198
authored
Jun 22, 2004
by
Tim Peters
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Improve the interface docs.
parent
7746bacf
Changes
1
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
103 additions
and
80 deletions
+103
-80
src/persistent/interfaces.py
src/persistent/interfaces.py
+103
-80
No files found.
src/persistent/interfaces.py
View file @
940a5198
...
...
@@ -40,16 +40,16 @@ class IPersistent(Interface):
- Sticky
This state is identical to the
up-to-date
state except that the
object cannot transition to the ghost state. This is a special
This state is identical to the
saved
state except that the
object cannot transition to the ghost state.
This is a special
state used by C methods of persistent objects to make sure that
state is not unloaded in the middle of computation.
In this state, the _p_changed attribute is non-None and false
and the _p_jar attribute is set to a data manager.
There is
, currently, no official way to detect whether an object
is in the
sticky state.
There is
no Python API for detecting whether an object is in the
sticky state.
- Changed
...
...
@@ -61,15 +61,22 @@ class IPersistent(Interface):
- Ghost
the object is in memory but its state has not been loaded from
the database (or has been unloaded). In this state, the object
doesn't contain any data.
the database (or its state has been unloaded). In this state,
the object doesn't contain any application data.
In this state, the _p_changed attribute is None, and the _p_jar
attribute is set to the data manager from which the object was
obtained.
In all the above, _p_oid (the persistent object id) is set when
_p_jar first gets set.
The following state transactions are possible:
- Unsaved -> Saved
This transition occurs when an object is saved in the
database. This usually happens when an unsaved object is added
database.
This usually happens when an unsaved object is added
to (e.g. as an attribute or item of) a saved (or changed) object
and the transaction is committed.
...
...
@@ -77,37 +84,37 @@ class IPersistent(Interface):
Sticky -> Changed
This transition occurs when someone sets an attribute or sets
_p_changed to a true value on a
n up-to-date or sticky
object. When the transition occurs, the persistent object is
re
quired to call the register method on its data manager,
passing itself as the
only argument.
_p_changed to a true value on a
saved or sticky object. When the
transition occurs, the persistent object is required to call the
re
gister() method on its data manager, passing itself as the
only argument.
- Saved -> Sticky
This transition occurs when C code marks the object as sticky to
prevent its deactivation
and transition to the ghost state
.
prevent its deactivation.
- Saved -> Ghost
This transition occurs when an saved object is deactivated, by:
calling _p_deactivate, setting _p_changed to None, or deleting
_p_changed.
This transition occurs when a saved object is deactivated or
invalidated. See discussion below.
- Sticky -> Saved
This transition occurs when C code unmarks the object as sticky to
allow its deactivation
and transition to the ghost state
.
allow its deactivation.
- Changed -> Saved
This transition occurs when a transaction is committed.
The data manager affects the transaction by setting _p_changed
to a true value.
This transition occurs when a transaction is committed. After
saving the state of a changed object during transaction commit,
the data manager sets the object's _p_changed to a non-None false
value.
- Changed -> Ghost
This transition occurs when a transaction is aborted.
The data manager affects the transaction by deleting _p_changed
.
This transition occurs when a transaction is aborted.
All changed
objects are invalidated by the data manager by an abort
.
- Ghost -> Saved
...
...
@@ -116,102 +123,120 @@ class IPersistent(Interface):
Note that there is a separate C API that is not included here.
The C API requires a specific data layout and defines the sticky
state that is used to prevent object deactivation while in C
routines.
state.
About Invalidation, Deactivation and the Sticky & Ghost States
The sticky state is intended to be a short-lived state, to prevent
an object's state from being discarded while we're in C routines. It
is an error to invalidate an object in the sticky state.
Deactivation is a request that an object discard its state (become
a ghost). Deactivation is an optimization, and a request to
deactivate may be ignored. There are two equivalent ways to
request deactivation:
- call _p_deactivate()
- set _p_changed to None
There is one way to invalidate an object: delete its _p_changed
attribute. This cannot be ignored, and is used when semantics
require invalidation. Normally, an invalidated object transitions
to the ghost state. However, some objects cannot be ghosts. When
these objects are invalidated, they immediately reload their state
from their data manager, and are then in the saved state.
"""
_p_jar
=
Attribute
(
"""The data manager for the object
_p_jar
=
Attribute
(
"""The data manager for the object
.
The data manager implements the IPersistentDataManager interface.
If there is no data manager, then this is None.
"""
)
_p_oid
=
Attribute
(
"""The object id
_p_oid
=
Attribute
(
"""The object id
.
It is up to the data manager to assign this.
The special value None is reserved to indicate that an object
id has not been assigned.
id has not been assigned. Non-None object ids must be hashable
and totally ordered.
"""
)
_p_changed
=
Attribute
(
_p_changed
=
Attribute
(
"""The persistent state of the object
This is one of:
None -- The object is a ghost.
It is not active.
None -- The object is a ghost.
false -- The object is saved (or has never been saved).
false
but not None
-- The object is saved (or has never been saved).
true -- The object has been modified.
true -- The object has been modified
since it was last saved
.
The object state may be changed by assigning this attribute,
however, assigning None is ignored if the object is not in the
up-to-date state.
The object state may be changed by assigning or deleting this
attribute; however, assigning None is ignored if the object is
not in the saved state, and may be ignored even if the object is
in the saved state.
Note that an object can
change to the modifi
ed state only if
it has a data manager. When such a state change occurs, the
'register' method of the data manager
is
called, passing the
Note that an object can
transition to the chang
ed state only if
it has a data manager.
When such a state change occurs, the
'register' method of the data manager
must be
called, passing the
persistent object.
Deleting this attribute forces deactivation independent of
existing state.
Note that an attribute is used for this to allow optimized
cache implementations.
Deleting this attribute forces invalidation independent of
existing state, although it is an error if the sticky state is
current.
"""
)
_p_serial
=
Attribute
(
"""The object serial number
_p_serial
=
Attribute
(
"""The object serial number
.
This is an arbitrary object.
"""
)
_p_atime
=
Attribute
(
"""The integer object access time, in seconds, modulus one day
This member is used by the data manager to distiguish distinct
revisions of a given persistent object.
XXX When does a day start, the current implementation appears
to use gmtime, but this hasn't be explicitly specified.
XXX Why just one day?
This is an 8-byte string (not Unicode).
"""
)
def
__getstate__
():
"""Get the object
state data
"""Get the object
data.
The state should not include persistent attributes ("_p_name")
The state should not include persistent attributes ("_p_name").
The result must be picklable.
"""
def
__setstate__
(
state
):
"""Set the object state data
Note that this does not affect the object's persistent state.
"""Set the object data.
"""
def
_p_activate
():
"""Activate the object
"""Activate the object
.
Change the object to the
up-to-date
state if it is a ghost.
Change the object to the
saved
state if it is a ghost.
"""
def
_p_deactivate
():
"""Deactivate the object
"""Deactivate the object
.
If possible, change an object in the up-to-date
state to the
Possibly change an object in the saved
state to the
ghost state. It may not be possible to make some persistent
objects ghosts.
objects ghosts, and, for optimization reasons, the implementation
may choose to keep an object in the saved state.
"""
class
IPersistentNoReadConflicts
(
IPersistent
):
def
_p_independent
():
"""Hook for subclasses to prevent read conflict errors
"""Hook for subclasses to prevent read conflict errors
.
A specific persistent object type can define this method and
have it return true if the data manager should ignore read
conflicts for this object.
"""
# XXX TODO: document conflict resolution.
class
IPersistentDataManager
(
Interface
):
"""Provide services for managing persistent state.
...
...
@@ -222,36 +247,34 @@ class IPersistentDataManager(Interface):
def
setstate
(
object
):
"""Load the state for the given object.
The object should be in the
deactivated (ghost)
state.
The object should be in the
ghost
state.
The object's state will be set and the object will end up
in the
up-to-date
state.
in the
saved
state.
The object must
implement
the IPersistent interface.
The object must
provide
the IPersistent interface.
"""
def
register
(
object
):
"""Register a IPersistent with the current transaction.
"""Register a
n
IPersistent with the current transaction.
This method provides some insulation of the persistent object
from details of transaction management. For example, it allows
the use of per-database-connection rather than per-thread
transaction managers.
A persistent object should not register with its data manager
more than once during a single transaction. XXX should is too
wishy-washy; we should probably guarantee that this is true,
and it might be.
This method must be called when the object transitions to
the changed state.
"""
def
mtime
(
object
):
"""Return the modification time of the object.
The modification time may not be known, in which case None
is returned.
is returned. If non-None, the return value is the kind of
timestamp supplied by Python's time.time().
"""
# XXX Should we keep the following? Doesn't seem too useful, and
# XXX we don't actually implement this interface (e.g., we have no
# XXX .statistics() method).
class
ICache
(
Interface
):
"""In-memory object cache
"""In-memory object cache
.
The cache serves two purposes. It peforms pointer swizzling, and
it keeps a bounded set of recently used but otherwise unreferenced
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment