Skip to content
Snippets Groups Projects
Commit 425db0d5 authored by Piotr Maślanka's avatar Piotr Maślanka
Browse files

fixed the docs for Monitor

parent 7b23788f
No related branches found
No related tags found
No related merge requests found
...@@ -25,3 +25,51 @@ It means that if it's hanging on I/O, for example, it won't be affected. ...@@ -25,3 +25,51 @@ It means that if it's hanging on I/O, for example, it won't be affected.
.. autoclass:: satella.coding.concurrent.TerminableThread .. autoclass:: satella.coding.concurrent.TerminableThread
:members: :members:
Monitor
=======
A monitor is a Java-like synchronization idea. Inheriting from Monitor outfits the class with a Lock
(or a reentrant lock, if *RMonitor* is used), that can be used to coordinate access to some shared resource.
Take care to invoke Monitor's constructor when inheriting, or this won't work.
You can decorate your methods with *Monitor.synchronized* to have them execute with the lock acquired.
If you have such a method, you can also temporarily release the lock using context manager _Monitor.release_
(it will be reacquired) when context manager is exited.
You can also use manual synchronization with context manager *Monitor.acquire*.
::
from satella.coding import Monitor
class MyProtectedClass(Monitor):
def __init__(self, *args):
super(Monitor, self).__init__()
@Monitor.synchronized
def synchronized(self):
pass # everything here is executed with class lock acquired
@Monitor.synchronized
def temporary_release(self):
pass # lock is acquired here
with Monitor.release(self):
pass # lock is NOT ACQUIRED here
pass # and here it's reacquired again
def manual_sync(self):
pass # not synchronized
with Monitor.acquire(self):
pass # synchronized
You can also use *Monitor.release* and *Monitor.acquire* with other objects than self, but exercise
caution and think over the consequences.
.. autoclass:: satella.coding.concurrent.Monitor
:members:
.. autoclass:: satella.coding.concurrent.RMonitor
# Monitor
A monitor is a Java-like synchronization idea. Inheriting from _Monitor_ outfits the class with a Lock
(or a reentrant lock, if _RMonitor_ is used), that can be used to coordinate access to some shared resource.
Take care to invoke _Monitor's_ constructor when inheriting, or this won't work.
You can decorate your methods with _Monitor.synchronized_ to have them execute with the lock acquired.
If you have such a method, you can also temporarily release the lock using context manager _Monitor.release_
(it will be reacquired) when context manager is exited.
You can also use manual synchronization with context manager _Monitor.acquire_.
```python
from satella.coding import Monitor
class MyProtectedClass(Monitor):
def __init__(self, *args):
super(Monitor, self).__init__()
@Monitor.synchronized
def synchronized(self):
pass # everything here is executed with class lock acquired
@Monitor.synchronized
def temporary_release(self):
pass # lock is acquired here
with Monitor.release(self):
pass # lock is NOT ACQUIRED here
pass # and here it's reacquired again
def manual_sync(self):
pass # not synchronized
with Monitor.acquire(self):
pass # synchronized
```
You can also use _Monitor.release_ and _Monitor.acquire_ with other objects than self, but exercise
caution and think over the consequences.
...@@ -8,7 +8,6 @@ Welcome to satella's documentation! ...@@ -8,7 +8,6 @@ Welcome to satella's documentation!
configuration/index configuration/index
configuration/schema configuration/schema
configuration/sources configuration/sources
coding/monitor
coding/functions coding/functions
coding/structures coding/structures
coding/concurrent coding/concurrent
......
...@@ -14,19 +14,19 @@ class Monitor: ...@@ -14,19 +14,19 @@ class Monitor:
Use it like that: Use it like that:
class MyProtectedObject(Monitor): >>> class MyProtectedObject(Monitor):
def __init__(self, *args, **kwargs): >>> def __init__(self, *args, **kwargs):
Monitor.__init__(self) >>> Monitor.__init__(self)
... do your job .. >>> ... do your job ..
@Monitor.synchronized >>> @Monitor.synchronized
def function_that_needs_mutual_exclusion(self): >>> def function_that_needs_mutual_exclusion(self):
.. do your threadsafe jobs .. >>> .. do your threadsafe jobs ..
def function_that_partially_needs_protection(self): >>> def function_that_partially_needs_protection(self):
.. do your jobs .. >>> .. do your jobs ..
with Monitor.acquire(self): >>> with Monitor.acquire(self):
.. do your threadsafe jobs .. >>> .. do your threadsafe jobs ..
""" """
def __init__(self, obj=None): def __init__(self, obj=None):
...@@ -60,16 +60,15 @@ class Monitor: ...@@ -60,16 +60,15 @@ class Monitor:
but you feel that you can release it for a while as it would but you feel that you can release it for a while as it would
improve parallelism. You can use it as such: improve parallelism. You can use it as such:
@Monitor.synchronized >>> @Monitor.synchronized
def protected_function(self): >>> def protected_function(self):
.. do some stuff that needs mutual exclusion .. >>> .. do some stuff that needs mutual exclusion ..
with Monitor.release(self): >>> with Monitor.release(self):
.. do some I/O that doesn't need mutual exclusion .. >>> .. do some I/O that doesn't need mutual exclusion ..
.. back to protected stuff .. >>> .. back to protected stuff ..
""" """
def __init__(self, foo): def __init__(self, foo: 'Monitor'):
self.foo = foo self.foo = foo
def __enter__(self): def __enter__(self):
...@@ -89,11 +88,11 @@ class Monitor: ...@@ -89,11 +88,11 @@ class Monitor:
Consider foo, which is a monitor. If you needed to lock it from Consider foo, which is a monitor. If you needed to lock it from
outside, you would do: outside, you would do:
with Monitor.acquire(foo): >>> with Monitor.acquire(foo):
.. do operations on foo that need mutual exclusion .. >>> .. do operations on foo that need mutual exclusion ..
""" """
def __init__(self, foo): def __init__(self, foo: 'Monitor'):
self.foo = foo self.foo = foo
def __enter__(self): def __enter__(self):
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment