From 5463509c7f8c15ae648eea644bea001a043d8b09 Mon Sep 17 00:00:00 2001 From: Fredrik Tolf Date: Fri, 23 Dec 2011 02:29:33 +0100 Subject: [PATCH] Documented pdm.perf as well. --- pdm/perf.py | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 94 insertions(+), 1 deletion(-) diff --git a/pdm/perf.py b/pdm/perf.py index 087d782..786ab98 100644 --- a/pdm/perf.py +++ b/pdm/perf.py @@ -1,6 +1,54 @@ +"""Python Daemon Management -- PERF utilities + +This module serves two purposes: It has a few utility classes +for implementing PERF interfaces in common ways, and uses those +classes to implement some standard PERF objects that can be used by +PERF clients connecting to any PERF server. + +See the documentation for pdm.srv.perf for a description of the +various PERF interfaces. + +It contains two named PERF objects: + + * sysres -- A directory containing the following objects pertaining + to the resource usage of the server process: + * realtime -- An attribute returning the amount of real time + since the PDM module was imported (which likely + coincides with the amount of time the server process + has been running). + * cputime -- An attribute returning the amount of CPU time + consumed by the server process (in both user and + kernel mode). + * utime -- An attribute returning the amount of CPU time the + server process has spent in user mode. + * stime -- An attribute returning the amount of CPU time the + server process has spent in kernel mode. + * maxrss -- An attribute returning the largest resident set size + the server process has used during its lifetime. + * rusage -- An attribute returning the current rusage of the + server process. +* sysinfo -- A directory containing the following objects pertaining + to the environment of the server process: + * pid -- An attribute returning the PID of the server process. + * uname -- An attribute returning the uname information of the + system. + * hostname -- An attribute returning the hostname of the system. + * platform -- An attribute returning the Python build platform. +""" + import os, sys, resource, time, socket, threading +__all__ = ["attrinfo", "simpleattr", "valueattr", "eventobj", + "staticdir", "event", "procevent", "startevent", + "finishevent"] + class attrinfo(object): + """The return value of the `attrinfo' method on `attr' objects as + described in pdm.srv.perf. + + Currently contains a single data field, `desc', which should have + a human-readable description of the purpose of the attribute. + """ def __init__(self, desc = None): self.desc = desc @@ -12,6 +60,10 @@ class perfobj(object): return [] class simpleattr(perfobj): + """An implementation of the `attr' interface, which is initialized + with a function, and returns whatever that function returns when + read. + """ def __init__(self, func, info = None, *args, **kwargs): super(simpleattr, self).__init__(*args, **kwargs) self.func = func @@ -29,6 +81,10 @@ class simpleattr(perfobj): return super(simpleattr, self).pdm_protocols() + ["attr"] class valueattr(perfobj): + """An implementation of the `attr' interface, which is initialized + with a single value, and returns that value when read. Subsequent + updates to the value are reflected in subsequent reads. + """ def __init__(self, init, info = None, *args, **kwargs): super(valueattr, self).__init__(*args, **kwargs) self.value = init @@ -45,8 +101,11 @@ class valueattr(perfobj): def pdm_protocols(self): return super(valueattr, self).pdm_protocols() + ["attr"] - class eventobj(perfobj): + """An implementation of the `event' interface. It keeps track of + subscribers, and will multiplex any event to all current + subscribers when submitted with the `notify' method. + """ def __init__(self, *args, **kwargs): super(eventobj, self).__init__(*args, **kwargs) self.subscribers = set() @@ -60,6 +119,7 @@ class eventobj(perfobj): self.subscribers.remove(cb) def notify(self, event): + """Notify all subscribers with the given event object.""" for cb in self.subscribers: try: cb(event) @@ -69,6 +129,10 @@ class eventobj(perfobj): return super(eventobj, self).pdm_protocols() + ["event"] class staticdir(perfobj): + """An implementation of the `dir' interface. Put other PERF + objects in it using the normal dict assignment syntax, and it will + return them to requesting clients. + """ def __init__(self, *args, **kwargs): super(staticdir, self).__init__(*args, **kwargs) self.map = {} @@ -95,6 +159,14 @@ class staticdir(perfobj): return super(staticdir, self).pdm_protocols() + ["dir"] class event(object): + """This class should be subclassed by all event objects sent via + the `event' interface. Its main utility is that it keeps track of + the time it was created, so that listening clients can precisely + measure the time between event notifications. + + Subclasses should make sure to call the __init__ method if they + override it. + """ def __init__(self): self.time = time.time() @@ -112,6 +184,21 @@ def getprocid(): idlock.release() class procevent(event): + """A subclass of the `event' class meant to group several events + related to the same process. Create a new process by creating (a + subclass of) the `startevent' class, and subsequent events in the + same process by passing that startevent as the `id' parameter. + + It works by having `startevent' allocate a unique ID for each + process, and every other procevent initializing from that + startevent copying the ID. The data field `id' contains the ID so + that it can be compared by clients. + + An example of such a process might be a client connection, where a + `startevent' is emitted when a client connects, another subclass + of `procevent' emitted when the client runs a command, and a + `finishevent' emitted when the connection is closed. + """ def __init__(self, id): super(procevent, self).__init__() if isinstance(id, procevent): @@ -120,10 +207,16 @@ class procevent(event): self.id = id class startevent(procevent): + """A subclass of `procevent'. See its documentation for details.""" def __init__(self): super(startevent, self).__init__(getprocid()) class finishevent(procevent): + """A subclass of `procevent'. Intended to be emitted when a + process finishes and terminates. The `aborted' field can be used + to indicate whether the process completed successfully, if such a + distinction is meaningful. The `start' parameter should be the + `startevent' instance used when the process was initiated.""" def __init__(self, start, aborted = False): super(finishevent, self).__init__(start) self.aborted = aborted -- 2.11.0