rrEvent Module

The module rrEvent is available in server event plugins only.

The module is already loaded/imported.

Writing server event plugins

Server event plugins are python scripts that are executed when specific events happen.

Royal Render reads the first comment block af an event script to get the settings of the plugin.

Information about the event plugin can be put in the event comment block, for example:

# Information about this event plugin
#
# rrPluginName:             Hello Event
# rrPluginAuthor:   Holger Schoenberger
# rrPluginVersion:  1.0
# rrPluginType:             Job Event Plugin
# rrRRversion:              8.2.00

The plugin information is optional and omitting it will not compromise the execution of an event plugin.

Instead, in order for the plugin to work, the lines of the first comment block must contain the name of an event, and enable it using the syntax

# event_name: true

Example, a server event plugin that is run when the job crashes, or its client has low memory or the job is disabled:

# __ ERROR EVENTS TO HANDLE: __
#
# eCrashed: true
# eClientLowSysMem: true
#
# __ LOG EVENTS TO HANDLE: __
#
# lDisable: true
#

job = rrEvent.getJob()
rrGlobal.writeLog2(rrGlobal.logLvL.info,
                   f"Event Plugin: {job.sceneName} crashed, or is low on memory, or was disabled")

Server event scripts must be copied to the folder [RR]/plugins64/server_events/

Error and Log Events

The identifiers can be set to “true” or “1” in the first comment block of the plugin, so that the script will be executed when that event occurs.

The list of names are taken from these enums:

enum rrJob._LogMessage()

enum rrJob._ErrorMessage().

Functions

Trigger functions

rrEvent.getJob() → rrJob._JobSend

Returns the job that triggered the event.

rrEvent.logCount() → int

Number of log events that triggered this plugin in the last ~45 seconds. It can be used in combination with logItem() in a for loop.

rrEvent.logItem((int)idx) → rrJob._Log

Get the log event at index idx. It can be used in combination with logCount() in a for loop.

Example, print out and log all the events that triggered the plugin in the last ~45 seconds:

for i in range(rrEvent.logCount()):
    log_event = rrEvent.logItem(i)
    rrGlobal.writeLog2(rrGlobal.logLvL.info,
                       "Log Message: " + log_event.logString())

rrEvent.errCount() → int

Number of error events that triggered this plugin in the last ~45s. It can be used in combination with errItem() in a for loop.

rrEvent.errItem(int idx) → rrJob._Error

Get the error event at index idx. It can be used in combination with errCount() in a for loop.

rrEvent.firstTime() → datetime.datetime

The time of the first event that triggered this plugin.

rrEvent.lastTime()

rrTime lastTime() -> datetime.datetime:

The last time this plugin was triggered.

rrEvent.allEvents() → str

Returns a string containing each event in one line with time and client name.

Example, write all the events that triggered the plugin in the server log:

rrGlobal.writeLog2(rrGlobal.logLvL.info,
                   "Event Plugin: All Events that triggered this plugin in the last ~45s: ")

rrGlobal.writeLog2(rrGlobal.logLvL.info,  rrEvent.allEvents())

Generic functions

rrEvent.whoAsString((int)whoId) → str

The rrJob._Error and rrJob._Log class have a parameter named .who This function converts rrJob._Error.who and rrJob._Log.who into a string.

rrEvent.jobAll_count() → int

Returns the number of all jobs available in this RR application. It can be used in combination with jobAll_get() in for loops.

rrEvent.jobAll_get(index) → rrJob._JobSend

Returns a copy of a job by its index. It can be used in combination with jobAll_count() in for loops.

Example, find all jobs submitted along the job that triggered the event, comparing their rrJob._JobSend.IDmain:

job = rrEvent.getJob()
id_main = job.IDmain()

job_count = rrEvent.jobAll_count()

siblings_id = []
for i in range(jobCount):
    a_job = rrEvent.jobAll_get(i)
    if a_job.IDmain() == id_main:
        siblings_id.append(selectedJob.ID)

rrEvent.clientAll_count() → int

Returns the number of clients. It can be used in combination with clientAll_get() in for loops.

rrEvent.clientAll_get((int)clientID) → libpyRR3._Client_ALL

Gets a client by its index. It can be used in combination with clientAll_count() in for loops.

Example, write the list of all clients in the server log:

rrGlobal.writeLog2(rrGlobal.logLvL.info,
                   "List all clients: ")

client_count = rrEvent.clientAll_count()

for i in range(client_count):
    client = rrEvent.clientAll_get(ic)
    rrGlobal.writeLog2(rrGlobal.logLvL.info,
                       "        " + client.name())

rrEvent.jobSendCommand((list)jobIDs, (rrJob._LogMessage)commandID, (int)commandParam) → bool

Send a Change Settings command to the rrServer. jobIDs is a list of rrJob._JobMinInfo.ID of jobs that you want to send a command to.

Note

The job in rrControl will not update until rrControl gets an update from the rrServer.

Example, disapprove the job that triggered the event:

job = rrEvent.getJob()
rrEvent.jobSendCommand([job.ID], rrJob._LogMessage.lDisApprove, 0)

rrEvent.clientSendCommand((list)clients, (int)commandID, str(param)) → bool

Sends a command to rrClients.

clients is a list of client IDs as positional integers. If the list has only one element and it equals -1, then the command is applied to all clients.

param is an optional string parameter. It can be used to send commandlines to the client with the commandID rrGlobal._ClientCommand.cCommandLine