developer.texinfo

This chapter is the official repository for the collected wisdom of the
Buildbot hackers.

It contains some sparse documentation of the inner workings of Buildbot, but of
course, the final reference for that is the source itself.

More importantly, this chapter represents the official repository of all
agreed-on patterns for use in Buildbot.  In this case, the source is a
@i{terrible} reference, because much of it is old and crusty.  But we are
trying to do things the new, better way, and those new, better ways are
described here.

@menu
* Buildmaster Service Hierarchy::
* Utilities::
* The Event Loop::
* String Types::
* Subscription Interfaces::
* Twisted Idioms::
* Testing Idioms and Utilities::
@end menu

@node Buildmaster Service Hierarchy
@section Buildmaster Service Hierarchy

TODO

@node Utilities
@section Utilities

@menu
* buildbot.util.eventual::
@end menu

@node buildbot.util.eventual
@subsection buildbot.util.eventual

This package provides a simple way to say "please do this later":

@example
from buildbot.util.eventual import eventually
def do_what_I_say(what, where):
    # ...
eventually(do_what_I_say, "clean up", "your bedroom")
@end example

The package defines "later" as "next time the reactor has control", so this is
a good way to avoid long loops that block other activity in the reactor.
Callables given to @code{eventually} are guaranteed to be called in the same
order as the calls to @code{eventually}.  Any errors from the callable are
logged, but will not affect other callables.

If you need a deferred that will fire "later", use @code{fireEventually}.  This
function returns a deferred that will not errback.

@node The Event Loop
@section The Event Loop

TODO

@node String Types
@section String Types

TODO

@node Subscription Interfaces
@section Subscription Interfaces

TODO use @code{buildbot.eventually}

@node Twisted Idioms
@section Twisted Idioms

TODO

@node Testing Idioms and Utilities
@section Testing Idioms and Utilities

TODO