From bc5f0007512fe07ed2b09f9ff3427a7366126f8c Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Thu, 11 Oct 2012 13:01:21 -0400 Subject: wrote FAM docs --- src/lib/Bcfg2/Server/FileMonitor/Gamin.py | 49 ++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 11 deletions(-) (limited to 'src/lib/Bcfg2/Server/FileMonitor/Gamin.py') diff --git a/src/lib/Bcfg2/Server/FileMonitor/Gamin.py b/src/lib/Bcfg2/Server/FileMonitor/Gamin.py index 23f5424d0..9134758b8 100644 --- a/src/lib/Bcfg2/Server/FileMonitor/Gamin.py +++ b/src/lib/Bcfg2/Server/FileMonitor/Gamin.py @@ -1,4 +1,5 @@ -""" Gamin driver for file alteration events """ +""" File monitor backend with `Gamin +`_ support. """ import os import stat @@ -7,12 +8,12 @@ from gamin import WatchMonitor, GAMCreated, GAMExists, GAMEndExist, \ from Bcfg2.Server.FileMonitor import Event, FileMonitor - class GaminEvent(Event): - """ - This class provides an event analogous to - python-fam events based on gamin sources. - """ + """ This class maps Gamin event constants to FAM :ref:`event codes + `. """ + + #: The map of gamin event constants (which mirror FAM event names + #: closely) to :ref:`event codes ` action_map = {GAMCreated: 'created', GAMExists: 'exists', GAMChanged: 'changed', GAMDeleted: 'deleted', GAMEndExist: 'endExist'} @@ -21,19 +22,38 @@ class GaminEvent(Event): Event.__init__(self, request_id, filename, code) if code in self.action_map: self.action = self.action_map[code] + __init__.__doc__ = Event.__init__.__doc__ class Gamin(FileMonitor): - """ file monitor with gamin support """ - __priority__ = 10 + """ File monitor backend with `Gamin + `_ support. """ + + #: The Gamin backend is fairly decent, particularly newer + #: releases, so it has a fairly high priority. + __priority__ = 90 def __init__(self, ignore=None, debug=False): FileMonitor.__init__(self, ignore=ignore, debug=debug) + + #: The :class:`Gamin.WatchMonitor` object for this monitor. self.mon = None + + #: The counter used to produce monotonically increasing + #: monitor handle IDs self.counter = 0 + + #: The queue used to record monitors that are added before + #: :func:`start` has been called and :attr:`mon` is created. self.add_q = [] + __init__.__doc__ = FileMonitor.__init__.__doc__ def start(self): + """ The Gamin watch monitor in :attr:`mon` must be created by + the daemonized process, so is created in ``start()``. Before + the :class:`Gamin.WatchMonitor` object is created, monitors + are added to :attr:`add_q`, and are created once the watch + monitor is created.""" FileMonitor.start(self) self.mon = WatchMonitor() for monitor in self.add_q: @@ -41,14 +61,18 @@ class Gamin(FileMonitor): self.add_q = [] def fileno(self): - return self.mon.get_fd() + if self.started: + return self.mon.get_fd() + else: + return None + fileno.__doc__ = FileMonitor.fileno.__doc__ def queue(self, path, action, request_id): - """queue up the event for later handling""" + """ Create a new :class:`GaminEvent` and add it to the + :attr:`events` queue for later handling. """ self.events.append(GaminEvent(request_id, path, action)) def AddMonitor(self, path, obj, handle=None): - """Add a monitor to path, installing a callback to obj.""" if handle is None: handle = self.counter self.counter += 1 @@ -69,11 +93,14 @@ class Gamin(FileMonitor): self.mon.watch_file(path, self.queue, handle) self.handles[handle] = obj return handle + AddMonitor.__doc__ = FileMonitor.AddMonitor.__doc__ def pending(self): return FileMonitor.pending(self) or self.mon.event_pending() + pending.__doc__ = FileMonitor.pending.__doc__ def get_event(self): if self.mon.event_pending(): self.mon.handle_one_event() return FileMonitor.get_event(self) + get_event.__doc__ = FileMonitor.get_event.__doc__ -- cgit v1.2.3-1-g7c22