3.4.15. 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:master -- buildbot.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:
  • remoteCommand -- RemoteCommandImpl 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 methodss:

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