Caution

Buildbot no longer supports Python 2.7 on the Buildbot master.

Caution

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

3.5.14. Protocols

To exchange information over the network between master and worker we need to use protocol.

buildbot.worker.protocols.base provide interfaces to implement wrappers around protocol specific calls, so other classes which use them do not need to know about protocol calls or handle protocol specific exceptions.

class buildbot.worker.protocols.base.Listener(master)
Parameters

masterbuildbot.master.BuildMaster instance

Responsible for spawning Connection instances and updating registrations. Protocol-specific subclasses are instantiated with protocol-specific parameters by the buildmaster during startup.

class buildbot.worker.protocols.base.Connection(master, worker)

Represents connection to single worker

proxies

Dictionary containing mapping between Impl classes and Proxy class for this protocol This may be overridden by subclass to declare its proxy implementations

createArgsProxies(args)
Returns

shallow copy of args dictionary with proxies instead of impls

Helper method that will use proxies, and replace Impl objects by specific Proxy counterpart.

notifyOnDisconnect(cb)
Parameters

cb – callback

Returns

buildbot.util.subscriptions.Subscription

Register a callback to be called if worker gets disconnected

loseConnection()

Close connection

remotePrint(message)
Parameters

message (string) – message for worker

Returns

Deferred

Print message to worker log file

remoteGetWorkerInfo()
Returns

Deferred

Get worker information, commands and version, put them in dictionary then return back

remoteSetBuilderList(builders)
Parameters

builders (List) – list with wanted builders

Returns

Deferred containing PB references XXX

Take list with wanted builders and send them to worker, return list with created builders

remoteStartCommand(remoteCommand, builderName, commandId, commandName, args)
Parameters
  • remoteCommandRemoteCommandImpl instance

  • builderName (string) – self explanatory

  • commandId (string) – command number

  • commandName (string) – command which will be executed on worker

  • args (List) – arguments for that command

Returns

Deferred

Start command on worker

remoteShutdown()
Returns

Deferred

Shutdown the worker, causing its process to halt permanently.

remoteStartBuild(builderName)

:param builderName name of the builder for which the build is starting :returns: Deferred

Just starts build

remoteInterruptCommand(builderName, commandId, why)
Parameters
  • builderName (string) – self explanatory

  • commandId (string) – command number

  • why (string) – reason to interrupt

Returns

Deferred

Interrupt the command executed on builderName with given commandId on worker, print reason “why” to worker logs

Following classes are describing the worker -> master part of the protocol.

In order to support old workers, we must make sure we do not change the current pb protocol. This is why we implement a Impl vs Proxy methods. All the objects that are referenced from the workers for remote calls have an Impl and a Proxy base classes in this module.

Impl classes are subclassed by buildbot master, and implement the actual logic for the protocol api. Proxy classes are implemented by the worker/master protocols, and implements the demux and de-serialization of protocol calls.

On worker sides, those proxy objects are replaced by a proxy object having a single method to call master side methods:

class buildbot.worker.protocols.base.workerProxyObject
callRemote(message, *args, **kw)

calls the method "remote_" + message on master side

class buildbot.worker.protocols.base.RemoteCommandImpl

Represents a RemoteCommand status controller

remote_update(updates)
Parameters

updates – dictionary of updates

Called when the workers has updates to the current remote command

possible keys for updates are:

  • stdout: Some logs where captured in remote command’s stdout. value: <data> as string

  • stderr: Some logs where captured in remote command’s stderr. value: <data> as string

  • header: remote command’s header text. value: <data> as  string

  • log: one of the watched logs has received some text. value: (<logname> as string, <data> as string)

  • rc: Remote command exited with a return code. value: <rc> as integer

  • elapsed: Remote command has taken <elapsed> time. value: <elapsed seconds> as float

  • stat: sent by the stat command with the result of the os.stat, converted to a tuple. value: <stat> as tuple

  • files: sent by the glob command with the result of the glob.glob. value: <files> as list of string

  • got_revision: sent by the source commands with the revision checked out. value: <revision> as string

  • repo_downloaded: sent by the repo command with the list of patches downloaded by repo. value: <downloads> as list of string

class buildbot.worker.protocols.base.FileWriterImpl

Class used to implement data transfer between worker and master

class buildbot.worker.protocols.base.FileReaderImpl(object)
remote_read(maxLength)
Parameters

maxLength – maximum length of the data to send

Returns

data read

called when worker needs more data

remote_close()

Called when master should close the file