lsst.utils  14.0-4-gac01bb5
lockProtection.py
Go to the documentation of this file.
1 #
2 # LSST Data Management System
3 # Copyright 2008, 2009, 2010 LSST Corporation.
4 #
5 # This product includes software developed by the
6 # LSST Project (http://www.lsst.org/).
7 #
8 # This program is free software: you can redistribute it and/or modify
9 # it under the terms of the GNU General Public License as published by
10 # the Free Software Foundation, either version 3 of the License, or
11 # (at your option) any later version.
12 #
13 # This program is distributed in the hope that it will be useful,
14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 # GNU General Public License for more details.
17 #
18 # You should have received a copy of the LSST License Statement and
19 # the GNU General Public License along with this program. If not,
20 # see <http://www.lsstcorp.org/LegalNotices/>.
21 #
22 
23 """
24 classes used to protect method from simultaneous access by different
25 threads. The primary class is LockProtected.
26 """
27 from builtins import object
28 import threading
29 
30 SharedLock = threading.RLock
31 
32 
33 class LockProtected(object):
34  """
35  a class that assists in keeping methods thread-safe.
36 
37  This class is intended to be enlisted as a base class to the class being
38  protected. A method that is to be protected from simultaneous access
39  would include (at its beginning) a call to _checkLocked():
40 
41  class MyClass(BaseClass, LockProtected):
42  def __init__(self, lock=SharedLock):
43  LockProtected.__init__(self, lock)
44  ...
45 
46  def dangerous(self):
47  self._checkLocked()
48  ...
49 
50  Doing so will require that the protected class be "locked" before a
51  protected method can be called or else an UnsafeAccessError will be
52  raised. Locking is done via the with statement:
53 
54  mc = MyClass()
55  with mc:
56  mc.dangerous()
57 
58  For the locking to work, the protected class must provide to the
59  LockProtected constructor a lock object. Typically this is a
60  lsst.utils.multithreading.SharedLock instance or, if one wants to
61  employ thread notification techniques, a
62  lsst.utils.multithreading.SharedData instance. It should at least
63  be a reentrant lock--that is, having the behavior of threading.RLock
64  (from the standard Python Library).
65 
66  This class is primarily intended for protecting methods across multiple
67  classes together via a single lock. That is, it can prevent simultaneous
68  access to any protected method across multiple class instances. To
69  accomplish this, each class to be protected should accept a lock as
70  a constructor argument. Then the same lock is passed into all of the
71  constructors that need protection together.
72  """
73 
74  def __init__(self, lock=None):
75  """
76  initialize the lock protection
77  @param lock a reentrant lock instance to use. If None, the
78  protection behavior is disabled.
79  """
80  # the shared lock
81  self._lp_lock = lock
82 
83  def __enter__(self):
84  if self._lp_lock:
85  self._lp_lock.acquire()
86 
87  def __exit__(self, exc_type, exc_value, traceback):
88  if self._lp_lock:
89  self._lp_lock.release()
90  return False
91 
92  def _checkLocked(self):
93  if self._lp_lock and not self._lp_lock._is_owned():
94  raise UnsafeAccessError()
95 
96 
97 class UnsafeAccessError(Exception):
98  """
99  an exception that is raised when one attempts to access a protected
100  method without first acquiring the lock on its class.
101  """
102 
103  def __init__(self, msg=None):
104  if not msg:
105  msg = "Programmer Error: failed to obtain lock via with statement"
106  Exception.__init__(self, msg)
def __exit__(self, exc_type, exc_value, traceback)