Moin,
the attached patch improves the documentation of the interface which distcc
provides to let people write monitoring software for distcc cluster. The
patch consists of a tiny fix to the API documentation in state.h, and an
appendix chapter to the manual which hopefully gives a helpful introduction
for people interested in writing monitors for distcc clusters.
Note that the appendix chapter is likely to be incomplete, I only documented
the parts which I deemed useful for people pondering to write distcc
monitors, and which I used myself. It would be nice of people could proofread
the patch, and improve it where necessary.
Committing this patch makes it easier for people to develop software for
distcc, which is IMHO a goal worth aiming for. I for one wished I had some
kind of introduction like this when I wrote my distcc monitor.
- Frerich
--
"If you fail to adjust your notion of fairness to the reality of the Universe,
you will probably not be happy." - Paratima, of http://free-dc.org fame
Index: linuxdoc/distcc.sgml
===================================================================
RCS file: /cvsroot/distcc/linuxdoc/distcc.sgml,v
retrieving revision 1.124
diff -u -3 -p -r1.124 distcc.sgml
--- linuxdoc/distcc.sgml 14 Jul 2003 02:42:45 -0000 1.124
+++ linuxdoc/distcc.sgml 29 Sep 2003 05:52:12 -0000
@@ -1429,7 +1429,7 @@ emerge </verb><em>packagename</em></tscr
</chapt> <!-- End of "The distccd Server" -->
-
+
<chapt>
<heading>Cross compiling</heading>
@@ -1503,5 +1503,194 @@ emerge </verb><em>packagename</em></tscr
and the gcc installation guide.
</p>
</chapt> <!-- end of "Cross compiling" -->
+
+ <appendix>
+ <chapt>
+ <heading>Writing Monitors for distcc</heading>
+
+ <p>
+ 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
+ <htmlurl url="http://lists.samba.org/listinfo/distcc"; name="distcc
+ mailinglist"> and present your problem.
+ </p>
+
+ <sect>
+ <heading>Possible Approaches</heading>
+
+ <p>
+ Right now, there are two general approaches which developers can follow
+ to develop distcc monitors:
+ </p>
+
+ <p>
+ <enum>
+ <item>
+ <p>
+ 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.
+ <p>
+ 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.
+ </item>
+ <item>
+ <p>
+ 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.
+ <p>
+ 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.
+ </item>
+ </enum>
+ </p>
+
+ <p>
+ 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.
+ </p>
+ </sect>
+
+ <sect>
+ <heading>The C Interface Provided by distcc</heading>
+
+ <p>
+ 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:
+ </p>
+
+ <p>
+ <descrip>
+ <tag>
+ <tt>int dcc_mon_poll(struct dcc_history **ppl)</tt>
+ </tag>
+ <p>
+ 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 errorcode.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.
+ </p>
+ <tag>
+ <tt>int dcc_history_free(struct dcc_history *)</tt>
+ </tag>
+ <p>
+ 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.
+ </p>
+ </descrip>
+ </p>
+
+ <p>
+ So generally, the algorithm you will employ is:
+ </p>
+
+ <p>
+ <enum>
+ <item>
+ Acquire a list of jobs by calling <tt>dcc_mon_poll</tt>.
+ </item>
+ <item>
+ Process the list of jobs, displaying results to the user.
+ </item>
+ <item>
+ Free the resources allocated by the list of jobs by calling
+ <tt>dcc_history_free</tt>.
+ </item>
+ </enum>
+ </p>
+
+ <p>
+ 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:
+ </p>
+
+ <p>
+ <descrip>
+ <tag>
+ <tt>unsigned long cpid</tt>
+ </tag>
+ <p>
+ The process ID of the compiler process for this job (on the
+ remote host).
+ </p>
+ <tag>
+ <tt>char file[128]</tt>
+ </tag>
+ <p>
+ The name of the input file of this job.
+ </p>
+ <tag>
+ <tt>char host[128]</tt>
+ </tag>
+ <p>
+ The name of the remote host this job is being processed on.
+ </p>
+ <tag>
+ <tt>int slot</tt>
+ </tag>
+ <p>
+ The CPU slot which is occupied by this job on the remote hosts.
+ </p>
+ <tag>
+ <tt>enum dcc_state curr_state</tt>
+ </tag>
+ <p>
+ 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.
+ </p>
+ <p>
+ Note that there's a convenience function
+ <tt>const char *dcc_get_state_name(enum dcc_state state)</tt>
+ 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.
+ </p>
+ <tag>
+ <tt>struct dcc_history *next</tt>
+ </tag>
+ <p>
+ A pointer to the next dcc_history struct in the list, or NULL if
+ this job is the last in the list.
+ </p>
+ </descrip>
+ </p>
+ </sect>
+ </chapt> <!-- end of "Writing Monitors for distcc" -->
+
</book>
</linuxdoc>
Index: src/mon.h
===================================================================
RCS file: /cvsroot/distcc/src/mon.h,v
retrieving revision 1.7
diff -u -3 -p -r1.7 mon.h
--- src/mon.h 23 Sep 2003 04:23:05 -0000 1.7
+++ src/mon.h 29 Sep 2003 05:52:12 -0000
@@ -41,7 +41,7 @@ extern "C" {
* The list is not sorted in any particular order, but it will tend to
* remain stable from one call to the next.
*
- * The caller should free the list through dcc_mon_list_free().
+ * The caller should free the list through dcc_history_free().
**/
int dcc_mon_poll(struct dcc_history **ppl);
__
distcc mailing list http://distcc.samba.org/
To unsubscribe or change options:
http://lists.samba.org/cgi-bin/mailman/listinfo/distcc
