You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat: blocking parameter on lock constructor with tests and docs (#325)
* feat: blocking param on lock constructor with tests and docs
* docs: replace a todo with actual doc
* better docs and additional test on blocking precedence
* fix: docs were broken
* docs: add a period .
Copy file name to clipboardExpand all lines: docs/index.rst
+54-12Lines changed: 54 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -89,18 +89,6 @@ already been done by other processes. For example, each process above first chec
89
89
it is already created, we should not destroy the work of other processes. This is typically the case when we want
90
90
just one process to write content into a file, and let every process to read the content.
91
91
92
-
The :meth:`acquire <filelock.BaseFileLock.acquire>` method accepts also a ``timeout`` parameter. If the lock cannot be
93
-
acquired within ``timeout`` seconds, a :class:`Timeout <filelock.Timeout>` exception is raised:
94
-
95
-
.. code-block:: python
96
-
97
-
try:
98
-
with lock.acquire(timeout=10):
99
-
withopen(file_path, "a") as f:
100
-
f.write("I have a bad feeling about this.")
101
-
except Timeout:
102
-
print("Another instance of this application currently holds the lock.")
103
-
104
92
The lock objects are recursive locks, which means that once acquired, they will not block on successive lock requests:
105
93
106
94
.. code-block:: python
@@ -124,6 +112,60 @@ The lock objects are recursive locks, which means that once acquired, they will
124
112
# And released here.
125
113
126
114
115
+
Timeouts and non-blocking locks
116
+
-------------------------------
117
+
The :meth:`acquire <filelock.BaseFileLock.acquire>` method accepts a ``timeout`` parameter. If the lock cannot be
118
+
acquired within ``timeout`` seconds, a :class:`Timeout <filelock.Timeout>` exception is raised:
119
+
120
+
.. code-block:: python
121
+
122
+
try:
123
+
with lock.acquire(timeout=10):
124
+
withopen(file_path, "a") as f:
125
+
f.write("I have a bad feeling about this.")
126
+
except Timeout:
127
+
print("Another instance of this application currently holds the lock.")
128
+
129
+
Using a ``timeout < 0`` makes the lock block until it can be acquired
130
+
while ``timeout == 0`` results in only one attempt to acquire the lock before raising a :class:`Timeout <filelock.Timeout>` exception (-> non-blocking).
131
+
132
+
You can also use the ``blocking`` parameter to attempt a non-blocking :meth:`acquire <filelock.BaseFileLock.acquire>`.
133
+
134
+
.. code-block:: python
135
+
136
+
try:
137
+
with lock.acquire(blocking=False):
138
+
withopen(file_path, "a") as f:
139
+
f.write("I have a bad feeling about this.")
140
+
except Timeout:
141
+
print("Another instance of this application currently holds the lock.")
142
+
143
+
144
+
The ``blocking`` option takes precedence over ``timeout``.
145
+
Meaning, if you set ``blocking=False`` while ``timeout > 0``, a :class:`Timeout <filelock.Timeout>` exception is raised without waiting for the lock to release.
146
+
147
+
You can pre-parametrize both of these options when constructing the lock for ease-of-use.
0 commit comments