[distcc] Improvement for the documentation of the monitoring interface

[Martin Pool]

In the absence of an HTML document, I'm going to put this in mon.h,
per this patch.  I corrected just a couple of typos and added some
more detail.



--- mon.h.~1.9.~	2003-09-29 16:44:43.000000000 +1000
+++ mon.h	2003-10-01 13:53:01.000000000 +1000
@@ -3,6 +3,7 @@
  * distcc -- A simple distributed compiler system
  *
  * Copyright (C) 2003 by Martin Pool <mbp at samba.org>
+ * Copyright (C) 2003 by Frerich Raabe <raabe at kde.org>
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License as
@@ -28,6 +29,171 @@
 extern "C" {
 #endif
 
+
+/*
+    
+   Writing Monitors for distcc
+   ---------------------------
+
+   It is possible for third party developers to write monitoring
+   software for distcc clusters, and you are encouranged to do
+   so. This appendix attempts to provide you with all the information
+   you'll need to write a distcc monitor, but just like all other
+   software, distcc is not perfect; in case you are stuck, can't seem
+   to get your monitor working, or just think a particular quirk in
+   the way a monitor was to be written is worth being pointed out,
+   don't hesitate to subscribe to the list (http://lists.samba.org/)
+   and present your problem.
+
+
+   Limitations on monitoring
+   -------------------------
+
+   As of distcc 2.11, monitoring information is only available for
+   currently running jobs originating from your machine and account.
+   There is no direct interface available for finding out about jobs
+   scheduled onto your machine by other users.
+
+   The state information is stored as files in the $DISTCC_DIR
+   (typically ~/.distcc/state), which are updated by client processes
+   as they run.  The goal of the design is to be adequately secure and
+   not to reduce the performance of compilation, which is after all
+   the whole point.
+
+   If you have permission to read the state files of some other users,
+   you can run a monitor on them by setting DISTCC_DIR before running
+   the monitor.
+
+   distcc does not maintain a history of tasks that have completed.
+   Your monitor program must do that if you want to present that
+   information.  mon-gnome.c has a simple implementation of this.
+   
+
+   
+   Possible Approaches
+   -------------------
+
+
+   Right now, there are two general approaches which developers can
+   follow to develop distcc monitors:
+
+   1 - Writing a program which parses the output of the distccmon-text
+   monitor. This is the most flexible solution, since it poses very
+   little requirements for the monitor - you are free to use whatever
+   programming language you prefer, and the only requirement your
+   software has is that the distccmon-text monitor exists on the user
+   systems, and that its output is compatible with the output of the
+   distccmon-text monitor you developed your software with.
+
+   Alas, the latter also embodies a problem, since parsing a programs
+   text output is fragile, and it's not guaranteed that the output format
+   of the distccmon-text monitor won't change in the future.
+
+
+   2 - Writing a program which links against distcc. This is the
+   cleaner solution from a software engineer's point of view, since
+   you retrieve the status information from distcc via, more or less
+   typesafe, data structures, and don't have to bother parsing text
+   output. The distcc functions and data types which your monitor will
+   probably want to use are declared in the header files exitcode.h,
+   mon.h and state.h.
+
+   Unfortunately, this requires that you use a programming language
+   which is able to link against the relevant distcc source files
+   (i.e. C or C++), and that the system which builds your monitor has
+   the distcc sources installed.  Also, it's currently not guaranteed
+   that the interface established by these three header files
+   maintains source or binary compatibility between distcc releases.
+
+   Since only the second approach requires detailed knowledge about the
+   interface to distcc's monitoring facilities, only the second approach
+   will be documented in this chapter. For the first approach, consult
+   your programming manuals for how to parse the stdout output of
+   external processes.
+
+
+   The C Interface Provided by distcc
+   ----------------------------------
+
+   In case you decide to let your monitor link directly against
+   distcc, you will get exposed to the interface which distcc offers
+   to provide your monitor with status information about the
+   cluster. The general concept behind this interface is that you
+   should poll distcc regularly for status information, and it will
+   return a list of jobs which are currently being processed on the
+   network. In practice, this interface is made up of the following
+   function:
+
+   int dcc_mon_poll(struct dcc_history **ppl)
+
+      This function, declared in the mon.h header file, allows you to
+      poll a list of jobs which are currently being processed on the
+      distcc cluster. It returns 0 in case the poll was successful,
+      otherwise one of the errors declared in the exitcode.h header
+      file.  The "ppl" list is a single-linked list of dcc_history
+      structs, which represent the "jobs" being worked on. The
+      dcc_history struct is declared in the state.h header file.
+
+
+   int dcc_history_free(struct dcc_history *)
+
+      Call this method and pass it the list of dcc_history structs you
+      acquired by calling dcc_mon_poll in order to free the resources
+      allocated by the list.
+
+   
+   So generally, the algorithm you will employ is:
+
+    - Acquire a list of jobs by calling dcc_mon_poll.
+
+    - Process the list of jobs, displaying results to the user.
+
+    - Free the resources allocated by the list of jobs by calling
+      dcc_history_free.
+      
+   For being able to do the second of the three steps listed above, you
+   will need to know what information the dcc_history struct (which
+   represents a job) provides. For a full list of properties, refer to
+   the state.h header file, for convenience here is a list of noteworthy
+   properties:
+
+   unsigned long cpid
+
+      The process ID of the compiler process for this job (on the remote
+      host).
+
+   char file[128]
+
+      The name of the input file of this job.
+
+   char host[128]
+
+      The name of the remote host this job is being processed on.
+
+   int slot
+
+      The CPU slot which is occupied by this job on the remote hosts.
+
+   enum dcc_state curr_state
+
+      This variable holds the current state of the job (i.e.  preprocess,
+      compile, send, receive etc.). Refer to the state.h header file for the
+      complete list of values declared in the dcc_state enumeration.
+
+      Note that there's a convenience function const char
+      *dcc_get_state_name(enum dcc_state state) declared in the state.h
+      header file which lets you retrieve a descriptive string
+      representation of the given enum, suitable for display to the user.
+
+   struct dcc_history *next
+
+      A pointer to the next dcc_history struct in the list, or NULL if this
+      job is the last in the list.
+
+*/
+
+
+
     
 /**
  * Read the list of running processes for this user.


-- 
Martin