/usr/lib/python2.7/dist-packages/Bcfg2/Server/FileMonitor/__init__.py is in bcfg2-server 1.4.0~pre2+git141-g6d40dace6358-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 | """ Bcfg2.Server.FileMonitor provides the support for monitoring
files. The FAM acts as a dispatcher for events: An event is detected
on a file (e.g., the file content is changed), and then that event is
dispatched to the ``HandleEvent`` method of an object that knows how
to handle the event. Consequently,
:func:`Bcfg2.Server.FileMonitor.FileMonitor.AddMonitor` takes two
arguments: the path to monitor, and the object that handles events
detected on that event.
``HandleEvent`` is called with a single argument, the
:class:`Bcfg2.Server.FileMonitor.Event` object to be handled.
Assumptions
-----------
The FAM API Bcfg2 uses is based on the API of SGI's `File Alteration
Monitor <http://oss.sgi.com/projects/fam/>`_ (also called "FAM").
Consequently, a few assumptions apply:
* When a file or directory is monitored for changes, we call that a
"monitor"; other backends my use the term "watch," but for
consistency we will use "monitor."
* Monitors can be set on files or directories.
* A monitor set on a directory monitors all files within that
directory, non-recursively. If the object that requested the
monitor wishes to monitor recursively, it must implement that
itself.
* Setting a monitor immediately produces "exists" and "endExist"
events for the monitored file or directory and all files or
directories contained within it (non-recursively).
* An event on a file or directory that is monitored directly yields
the full path to the file or directory.
* An event on a file or directory that is *only* contained within a
monitored directory yields the relative path to the file or
directory within the monitored parent. It is the responsibility of
the handler to reconstruct full paths as necessary.
* Each monitor that is set must have a unique ID that identifies it,
in order to make it possible to reconstruct full paths as
necessary. This ID will be stored in
:attr:`Bcfg2.Server.FileMonitor.FileMonitor.handles`. It may be any
hashable value; some FAM backends use monotonically increasing
integers, while others use the path to the monitor.
Base Classes
------------
"""
import os
import sys
import fnmatch
import Bcfg2.Options
from time import sleep, time
from Bcfg2.Logger import Debuggable
class Event(object):
""" Base class for all FAM events. """
def __init__(self, request_id, filename, code):
"""
:param request_id: The handler ID of the monitor that produced
this event
:type request_id: Varies
:param filename: The file or directory on which the event was
detected. An event on a file or directory
that is monitored directly yields the full
path to the file or directory; an event on a
file or directory that is *only* contained
within a monitored directory yields the
relative path to the file or directory within
the monitored parent.
:type filename: string
:param code: The :ref:`event code
<development-fam-event-codes>` produced. I.e.,
the type of event.
:type code: string
"""
#: The handler ID of the monitor that produced this event
self.requestID = request_id
#: The file or directory on which the event was detected. An
#: event on a file or directory that is monitored directly
#: yields the full path to the file or directory; an event on
#: a file or directory that is *only* contained within a
#: monitored directory yields the relative path to the file or
#: directory within the monitored parent.
self.filename = filename
#: The :ref:`event code <development-fam-event-codes>`
#: produced. I.e., the type of event.
self.action = code
def code2str(self):
""" Return the :ref:`event code <development-fam-event-codes>`
for this event. This is just an alias for :attr:`action`. """
return self.action
def __str__(self):
return "%s: %s %s" % (self.__class__.__name__,
self.filename, self.action)
def __repr__(self):
return "%s (request ID %s)" % (str(self), self.requestID)
class FileMonitor(Debuggable):
""" The base class that all FAM implementions must inherit.
The simplest instance of a FileMonitor subclass needs only to add
monitor objects to :attr:`handles` and received events to
:attr:`events`; the basic interface will handle the rest. """
options = [
Bcfg2.Options.Option(
cf=('server', 'ignore_files'),
help='File globs to ignore',
type=Bcfg2.Options.Types.comma_list,
default=['*~', '*#', '.#*', '*.swp', '*.swpx', '.*.swx',
'SCCS', '.svn', '4913', '.gitignore'])]
#: The relative priority of this FAM backend. Better backends
#: should have higher priorities.
__priority__ = -1
#: List of names of methods to be exposed as XML-RPC functions
__rmi__ = Debuggable.__rmi__ + ["list_event_handlers"]
def __init__(self):
"""
:param ignore: A list of filename globs describing events that
should be ignored (i.e., not processed by any
object)
:type ignore: list of strings (filename globs)
:param debug: Produce debugging information about the events
received and handled.
:type debug: bool
.. -----
.. autoattribute:: __priority__
"""
Debuggable.__init__(self)
#: A dict that records which objects handle which events.
#: Keys are monitor handle IDs and values are objects whose
#: ``HandleEvent`` method will be called to handle an event
self.handles = dict()
#: Queue of events to handle
self.events = []
#: List of filename globs to ignore events for. For events
#: that include the full path, both the full path and the bare
#: filename will be checked against ``ignore``.
self.ignore = Bcfg2.Options.setup.ignore_files
#: Whether or not the FAM has been started. See :func:`start`.
self.started = False
def __str__(self):
return "%s: %s" % (__name__, self.__class__.__name__)
def __repr__(self):
return "%s (%s events, fd %s)" % (self.__class__.__name__,
len(self.events),
self.fileno())
def start(self):
""" Start threads or anything else that needs to be done after
the server forks and daemonizes. Note that monitors may (and
almost certainly will) be added before ``start()`` is called,
so if a backend depends on being started to add monitors,
those requests will need to be enqueued and added after
``start()``. See
:class:`Bcfg2.Server.FileMonitor.Inotify.Inotify` for an
example of this. """
self.started = True
def should_ignore(self, event):
""" Returns True if an event should be ignored, False
otherwise. For events that include the full path, both the
full path and the bare filename will be checked against
:attr:`ignore`. If the event is ignored, a debug message will
be logged with :func:`debug_log`.
:param event: Check if this event matches :attr:`ignore`
:type event: Bcfg2.Server.FileMonitor.Event
:returns: bool - Whether not to ignore the event
"""
for pattern in self.ignore:
if (fnmatch.fnmatch(event.filename, pattern) or
fnmatch.fnmatch(os.path.split(event.filename)[-1],
pattern)):
self.debug_log("Ignoring %s" % event)
return True
return False
def pending(self):
""" Returns True if there are pending events (i.e., events in
:attr:`events` that have not been processed), False
otherwise. """
return bool(self.events)
def get_event(self):
""" Get the oldest pending event in :attr:`events`.
:returns: :class:`Bcfg2.Server.FileMonitor.Event`
"""
return self.events.pop(0)
def fileno(self):
""" Get the file descriptor of the file monitor thread.
:returns: int - The FD number
"""
return 0
def handle_one_event(self, event):
""" Handle the given event by dispatching it to the object
that handles it. This is only called by
:func:`handle_event_set`, so if a backend overrides that
method it does not necessarily need to implement this
function.
:param event: The event to handle.
:type event: Bcfg2.Server.FileMonitor.Event
:returns: None
"""
if not self.started:
self.start()
if self.should_ignore(event):
return
if event.requestID not in self.handles:
self.logger.info("Got event for unexpected id %s, file %s" %
(event.requestID, event.filename))
return
self.debug_log("Dispatching event %s %s to obj %s" %
(event.code2str(), event.filename,
self.handles[event.requestID]))
try:
self.handles[event.requestID].HandleEvent(event)
except KeyboardInterrupt:
raise
except: # pylint: disable=W0702
err = sys.exc_info()[1]
self.logger.error("Error in handling of event %s for %s: %s" %
(event.code2str(), event.filename, err))
def handle_event_set(self, lock=None):
""" Handle all pending events.
:param lock: A thread lock to use while handling events. If
None, then no thread locking will be performed.
This can possibly lead to race conditions in
event handling, although it's unlikely to cause
any real problems.
:type lock: threading.Lock
:returns: None
"""
if not self.started:
self.start()
count = 0
start = time()
if lock:
lock.acquire()
while self.pending():
self.handle_one_event(self.get_event())
count += 1
if lock:
lock.release()
end = time()
if count > 0:
self.logger.info("Handled %d events in %.03fs" % (count,
(end - start)))
def handle_events_in_interval(self, interval):
""" Handle events for the specified period of time (in
seconds). This call will block for ``interval`` seconds and
handle all events received during that period by calling
:func:`handle_event_set`.
:param interval: The interval, in seconds, during which events
should be handled. Any events that are
already pending when
:func:`handle_events_in_interval` is called
will also be handled.
:type interval: int
:returns: None
"""
if not self.started:
self.start()
end = time() + interval
while time() < end:
if self.pending():
self.handle_event_set()
end = time() + interval
else:
sleep(0.5)
def shutdown(self):
""" Handle any tasks required to shut down the monitor. """
self.debug_log("Shutting down %s file monitor" %
self.__class__.__name__)
self.started = False
def AddMonitor(self, path, obj, handleID=None):
""" Monitor the specified path, alerting obj to events. This
method must be overridden by a subclass of
:class:`Bcfg2.Server.FileMonitor.FileMonitor`.
:param path: The path to monitor
:type path: string
:param obj: The object whose ``HandleEvent`` method will be
called when an event is produced.
:type obj: Varies
:param handleID: The handle ID to use for the monitor. This
is useful when requests to add a monitor must
be enqueued and the actual monitors added
after :func:`start` is called.
:type handleID: Varies
:returns: Varies - The handler ID for the newly created
monitor
"""
raise NotImplementedError
def list_event_handlers(self):
""" XML-RPC that returns
:attr:`Bcfg2.Server.FileMonitor.FileMonitor.handles` for
debugging purposes. """
rv = dict()
for watch, handler in self.handles.items():
rv[watch] = getattr(handler, "name", handler.__class__.__name__)
return rv
#: A module-level FAM object that all plugins, etc., can use. This
#: should not be used directly, but retrieved via :func:`get_fam`.
_FAM = None
def get_fam():
""" Get a
:class:`Bcfg2.Server.FileMonitor.FileMonitor` object. If
:attr:`_FAM` has not been populated, then a new default
FileMonitor will be created.
:returns: :class:`Bcfg2.Server.FileMonitor.FileMonitor`
"""
global _FAM # pylint: disable=W0603
if _FAM is None:
_FAM = Bcfg2.Options.setup.filemonitor()
return _FAM
#: A dict of all available FAM backends. Keys are the human-readable
#: names of the backends, which are used in bcfg2.conf to select a
#: backend; values are the backend classes. In addition, the
#: ``default`` key will be set to the best FAM backend as determined
#: by :attr:`Bcfg2.Server.FileMonitor.FileMonitor.__priority__`
available = dict() # pylint: disable=C0103
# TODO: loading the monitor drivers should be automatic
try:
from Bcfg2.Server.FileMonitor.Pseudo import Pseudo
available['pseudo'] = Pseudo
except ImportError:
pass
try:
from Bcfg2.Server.FileMonitor.Gamin import Gamin
available['gamin'] = Gamin
except ImportError:
pass
try:
from Bcfg2.Server.FileMonitor.Inotify import Inotify
available['inotify'] = Inotify
except ImportError:
pass
for fdrv in reversed(sorted(available.keys(),
key=lambda k: available[k].__priority__)):
if fdrv in available:
available['default'] = available[fdrv]
break
|