74 lines
3.7 KiB
ReStructuredText
74 lines
3.7 KiB
ReStructuredText
Inner structure
|
|
===============
|
|
|
|
Main-Memory DataBase
|
|
--------------------
|
|
|
|
* Represented via Python dictionary (:code:`dict`).
|
|
Future version may include more abstract options, i.e. :class:`ptvp35.DbConnection` would be generic over :attr:`ptvp35.DbConnection.__mmdb` field
|
|
* Keys and values are almost guaranteed to be serializable.
|
|
All KVPs loaded on :code:`__aenter__` are re-serialized during file reload.
|
|
All KVPs added via submit-like methods are serialized before being added to the MMDB.
|
|
|
|
DataBase Stream File
|
|
--------------------
|
|
|
|
* In current implementation, all database storage storage files are Newline-Delimited JSON streams (https://en.wikipedia.org/wiki/JSON_streaming#Newline-Delimited_JSON).
|
|
.. code-block:: json
|
|
|
|
{"key": ["tuple", "example"], "value": {"dict": "example"}}
|
|
{"key": 123, "value": null}
|
|
* During the runtime, the database uses 6 different files:
|
|
* `.db` Main file.
|
|
Should be the only non-error file after correct shutdown.
|
|
* `.db.backup` Backup file.
|
|
Generated when the main file is being rebuilt.
|
|
* `.db.recover` Flag file.
|
|
Indicates that backup file is valid and that main file's validity is undefined.
|
|
* `.db.truncate` Auxiliary file created on each write to main file.
|
|
Contains 16 bytes little-endian representation of up to how many characters the main file is valid.
|
|
* `.db.truncate_flag` Flag file.
|
|
Indicates that truncate file is valid and that main file's validity after the specified character count is undefined.
|
|
* `.db.error` Error log file.
|
|
In current implementation, it contains only the main file contents that got truncated on recovery.
|
|
* All storage file writes are :code:`fsync`'ed.
|
|
* :code:`pathlib.Path.write_bytes` usecase relies on synchronisation/file-creation ordering. That may get replaced in future versions.
|
|
|
|
Request Queue
|
|
-------------
|
|
|
|
Transaction View (:class:`ptvp35.TransactionView`)
|
|
--------------------------------------------------
|
|
|
|
Connection-like interface on top of another connection-like interface.
|
|
|
|
* Provides most of the same methods as :class:`ptvp35.DbConnection`.
|
|
* From the common :class:`ptvp35.VirtualConnection` interface/base class:
|
|
* :meth:`ptvp35.TransactionView.get`
|
|
* :meth:`ptvp35.TransactionView.commit_transaction`
|
|
* :meth:`ptvp35.TransactionView.submit_transaction_request`
|
|
* :meth:`ptvp35.TransactionView.loop`
|
|
* :meth:`ptvp35.TransactionView.transaction` (default implementation)
|
|
* Non-standard common methods:
|
|
* :meth:`ptvp35.TransactionView.set_nowait`
|
|
* :meth:`ptvp35.TransactionView.submit_transaction`
|
|
* :meth:`ptvp35.TransactionView.commit`
|
|
* Does not have the the analogue for the :meth:`ptvp35.DbConnection.set` method.
|
|
* The reason for that is :code:`set` method having semantics contradictory to transactions.
|
|
* The :code:`set` provides a way to set a *single* value and wait until it's committed.
|
|
* Transaction are meant for a more fine control.
|
|
* The equivalent would consist of the three method calls:
|
|
* :meth:`ptvp35.TransactionView.set_nowait` to set the value in :code:`__delta`.
|
|
* :meth:`ptvp35.TransactionView.submit` to pass all the :code:`__delta` values.
|
|
* :meth:`ptvp35.TransactionView.commit` wait until all changes are commited.
|
|
|
|
Transaction (:class:`ptvp35.Transaction`)
|
|
-----------------------------------------
|
|
|
|
Manages a Transaction View.
|
|
|
|
* Creates and returns a Transaction View on :code:`__aenter__`/:code:`__enter__`.
|
|
* Submits changes on successful :code:`__exit__`.
|
|
* Commits changes on successful :code:`__aexit__`.
|
|
* Rolls back changes on unsuccessful :code:`__exit__`/:code:`__aexit__`.
|