Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see https://docs.buildbot.net/current/.

2.6.7. Writing a New Latent Worker Implementation

Writing a new latent worker should only require subclassing buildbot.worker.AbstractLatentWorker and implementing start_instance and stop_instance at a minimum.

2.6.7.1. AbstractLatentWorker

class buildbot.worker.AbstractLatentWorker

This class is the base class of all latent workers and implements some common functionality. A custom worker should only need to override start_instance and stop_instance methods.

See buildbot.worker.ec2.EC2LatentWorker for an example.

Additionally, builds_may_be_incompatible and isCompatibleWithBuild members must be overridden if some qualities of the new instances is determined dynamically according to the properties of an incoming build. An example a build may require a certain Docker image or amount of allocated memory. Overriding these members ensures that builds aren’t ran on incompatible workers that have already been started.

start_instance(self)

This method is responsible for starting instance that will try to connect with this master. A deferred should be returned.

Any problems should use an errback or exception. When the error is likely related to infrastructure problem and the worker should be paused in case it produces too many errors, then LatentWorkerFailedToSubstantiate should be thrown. When the error is related to the properties of the build request, such as renderable Docker image, then LatentWorkerCannotSubstantiate should be thrown.

The callback value can be None, or can be an iterable of short strings to include in the “substantiate success” status message, such as identifying the instance that started. Buildbot will ensure that a single worker will never have its start_instance called before any previous calls to start_instance or stop_instance finish. Additionally, for each start_instance call, exactly one corresponding call to stop_instance will be done eventually.

stop_instance(self, fast=False)

This method is responsible for shutting down instance. A deferred should be returned. If fast is True then the function should call back as soon as it is safe to do so, as, for example, the master may be shutting down. The value returned by the callback is ignored. Buildbot will ensure that a single worker will never have its stop_instance called before any previous calls to stop_instance finish. During master shutdown any pending calls to start_instance or stop_instance will be waited upon finish.

builds_may_be_incompatible

Determines if new instances have qualities dependent on the build. If True, the master will call isCompatibleWithBuild to determine whether new builds are compatible with the started instance. Unnecessarily setting builds_may_be_incompatible to True may result in unnecessary overhead when processing the builds. By default, this is False.

isCompatibleWithBuild(self, build_props)

This method determines whether a started instance is compatible with the build that is about to be started. build_props is the properties of the build that are known before the build has been started. A build may be incompatible with already started instance if, for example, it requests a different amount of memory or a different Docker image. A deferred should be returned, whose callback should return True if build is compatible and False otherwise. The method may be called when the instance is not yet started and should indicate compatible build in that case. In the default implementation the callback returns True.

check_instance(self)

This method determines the health of an instance. The method is expected to return a tuple with two members: is_good and message. The first member identifies whether the instance is still valid. It should be False if the method determined that a serious error has occurred and worker will not connect to the master. In such case, message should identify any additional error message that should be displayed to Buildbot user.

In case there is no additional messages, message should be an empty string.

Any exceptions raised from this method are interpreted as if the method returned False.