[tor-commits] [sbws/master] Document the state.dat file a little bit
pastly at torproject.org
pastly at torproject.org
Thu Aug 9 14:21:19 UTC 2018
commit 2df82656c60e0570c270720e305727512e6962c4
Author: Matt Traudt <sirmatt at ksu.edu>
Date: Mon Jul 16 15:08:55 2018 -0400
Document the state.dat file a little bit
---
README.md | 2 ++
docs/source/index.rst | 1 +
docs/source/sbws.util.rst | 8 ++++++++
docs/source/state.rst | 20 ++++++++++++++++++++
4 files changed, 31 insertions(+)
diff --git a/README.md b/README.md
index 74da116..0fa6118 100644
--- a/README.md
+++ b/README.md
@@ -136,6 +136,8 @@ In this directory you will find
- `datadir` Once your sbws scanner has started gathering results, it will dump
them into this directory. Other sbws commands (such as generate and stats)
read results from the files in this directory.
+- `state.dat` A file for storing state needed between sbws commands. See its
+ documentation for more information.
## Running tests
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 43eb373..7f3a993 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -25,6 +25,7 @@ Contents
faq
glossary
diagrams
+ state
sbws
Proposals
diff --git a/docs/source/sbws.util.rst b/docs/source/sbws.util.rst
index dd62d26..a1b3840 100644
--- a/docs/source/sbws.util.rst
+++ b/docs/source/sbws.util.rst
@@ -28,6 +28,14 @@ sbws.util.parser module
:undoc-members:
:show-inheritance:
+sbws.util.state module
+~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: sbws.util.state
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
sbws.util.stem module
~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/source/state.rst b/docs/source/state.rst
new file mode 100644
index 0000000..b61b69e
--- /dev/null
+++ b/docs/source/state.rst
@@ -0,0 +1,20 @@
+The ``state.dat`` file
+======================
+
+This file contains state that multiple sbws commands may want access to and
+that needs to persist across processes. Both read and write access to this file
+is wrapped in the ``State`` class, allowing for safe concurrent access: the
+file is locked before reading or writing, and (for now) only simple data types
+are allowed so we can be sure to update the state file on disk every time the
+state is modified in memory.
+
+At the time of writing, the following fields can exist in the state file.
+
+``scanner_started``
+-------------------
+
+The last time ``sbws scanner`` was started.
+
+- **Producer**: ``sbws scanner``, once at startup.
+
+- **Consumer**: ``sbws generate``, once each time it is ran.
More information about the tor-commits
mailing list