Deadline Scripting Reference  10.1.23.6
FranticX.Processes.ManagedProcess Class Reference

A base class for managing a process. More...

Inherited by Deadline.Plugins.DeadlinePlugin.

Classes

class  RegexHandlerCallback
 A regular expression callback class to handle lines of stdout. More...
 

Public Types

enum class  AbortLevel { Minor , Major , Fatal , Success }
 The different levels when aborting a render. More...
 

Public Member Functions

void AbortRender (string message)
 Aborts the render with a Major abort level. More...
 
void AbortRender (string message, AbortLevel level)
 Aborts the render with the given abort level. More...
 
void AddExitCodeToIgnore (int exitCode)
 Adds an exit code that should be ignored. More...
 
void AddPopupHandler (string regexTitle, string buttons)
 Adds a popup handler to press one or more buttons when a matching popup is detected. More...
 
void AddPopupHandler (string regexTitle, string regexContent, string buttons)
 Adds a popup handler to press one or more buttons when a matching popup is detected. More...
 
void AddPopupIgnorer (string regexTitle)
 Adds a popup ignorer. If a matching popup is detected, it is ignored. This should not be used on popups that block the rendering process (AddPopupHandler should be used in this case). More...
 
void AddPopupIgnorer (string regexTitle, string regexContent)
 Adds a popup ignorer. If a matching popup is detected, it is ignored. This should not be used on popups that block the rendering process (AddPopupHandler should be used in this case). More...
 
RegexHandlerCallback AddStdoutHandlerCallback (string regexString)
 Adds a stdout handler that can be used to handle a matching line of stdout. A RegexHandlerCallback object is returned, and a callback can be assigned to this object's HandleCallback property to handle a matching line of stdout. More...
 
RegexHandlerCallback AddStdoutHandlerEvent (string regexString)
 DEPRECATED: Use AddStdoutHandlerCallback. More...
 
void ClearEnvironmentVariables ()
 Clears the extra environment variables for the rendering process. More...
 
bool EnvironmentVariableExists (string key)
 Checks if the environment with the given key exists. More...
 
string GetEnvironmentVariable (string key)
 Gets the extra environment variable for the rendering process with the given key. If the variable is not defined, an empty string is returned. More...
 
string GetPreviousStdoutLine ()
 Gets the previous line of stdout. This should be called from a callback for a stdout handler to get the line before the current one. More...
 
string GetRegexMatch (int index)
 Gets the matched text at the given index for the current regular expression. This should be called from a callback for a stdout handler to get a match from the current line being handled. More...
 
 ManagedProcess ()
 Constructor. More...
 
void RedirectStdoutToFile (string filename)
 Redirect stdout for this render to the specified file. This should be called from the callback to initialize the process to ensure that all stdout goes to the file. More...
 
void ResetProcessAffinity ()
 Resets the affinity settings for the process. More...
 
void SetEnvironmentVariable (string key, string value)
 Sets extra environment variables for the rendering process only. This will take precedence over a variable in the current environment with the same name. More...
 
void SetUpdateTimeout (int timeout)
 Sets the update timeout. A timeout error will occur if the process goes the specified number of seconds without any stdout being printed out. More...
 
void SuppressThisLine ()
 Suppresses the next line of stdout. This should be called from a callback for a stdout handler to suppress the current line being handled. More...
 

Static Public Member Functions

static bool DetectLoop (MethodBase info)
 

Properties

bool AsynchronousStdout [get, set]
 Gets or sets if stdout redirection is asynchronous. This is ignored if StdoutRedirection is disabled. This is also ignored on Windows. More...
 
bool CreateNewConsole [get, set]
 Gets or sets if a new console should be created. More...
 
bool DebugLogging [get, set]
 Gets or sets if debug logging is enabled. More...
 
string Domain [get, set]
 The domain when running the process as a different user. This is ignored on Linux and Mac OSX. More...
 
bool FatalPythonErrors [get, set]
 Gets or sets if python errors should be treated as fatal errors. More...
 
bool HandleQtPopups [get, set]
 Gets or sets whether or not the process should handle Qt popups More...
 
bool HandleWindows10Popups [get, set]
 Gets or sets whether or not the process should handle Windows10 popups More...
 
bool HideDosWindow [get, set]
 Gets or sets of the Dos window should be hidden. More...
 
bool ImmediateTermination [get, set]
 Gets or sets if the process should terminate immediately instead of being allowed to shutdown gracefully. More...
 
int MaxHandledLineSize [get, set]
 Gets or sets the maximum line size that will be handled by the stdout handlers. Set to 0 to disable stdout handling. More...
 
string Password [get, set]
 The password when running the process as a different user. This is ignored on Linux and Mac OSX. More...
 
string[] PopupButtonClasses [get, set]
 Gets or sets the list of class names that the popup handlers considers to be buttons. More...
 
bool PopupHandling [get, set]
 Gets or sets if popup handling is enabled. More...
 
int PopupMaxChildWindows [get, set]
 Gets or sets the maximum number of controls that can be in a popup window. If a popup has more then this, it will not be considered a popup and will be ignored. More...
 
string[] PopupTextClasses [get, set]
 Gets or sets the list of class names that the popup handlers considers to be text fields. More...
 
bool PreserveEnvironment [get, set]
 If true, the environment will be preserved when running the process as another user using 'su' or 'sudo'. This is ignored on Windows. More...
 
bool PressEnterDuringRender [get, set]
 Gets or sets if the Enter button should be pressed shortly after starting the process. This can be useful if the process requires a key press to exit after it finishes running. More...
 
int[] ProcessAffinity [get, set]
 Gets or sets the affinity for the process (Windows and Linux only). If set to an empty list, the default affinity will be used. More...
 
ProcessPriorityClass ProcessPriority [get, set]
 Gets or sets the process priority class. This should typically be set to ProcessPriorityClass.BelowNormal so that the machine is still interactive during a heavy render. More...
 
bool RunAsUser [get, set]
 If true, the process will run as the user specified in UserName. More...
 
bool RunAsUserWithSu [get, set]
 If true, 'su' will be used to run the process as another user instead of 'sudo'. This is ignored on Windows. More...
 
bool SetHomeVariable [get, set]
 If true, the HOME environment variable will be set to the users home directory when running sudo. Not compatible with su. This is ignored on Windows. More...
 
bool SimulateLogin [get, set]
 If true, 'su' will simulate a login by the user we are running as. More...
 
string StdOutEncoding [get, set]
 Used to specify the name of the Character Encoding that will be used to decode StdOut and StdErr. More...
 
bool StdoutHandling [get, set]
 Gets or sets if stdout handling is enabled. This is ignored if StdoutRedirection is disabled. More...
 
bool StdoutRedirection [get, set]
 Gets or sets if stdout redirection is enabled. More...
 
bool TerminateOnExit [get, set]
 Gets or sets of the process should be terminated on exit. More...
 
bool UseExtraEnvironmentVariablesOnly [get, set]
 If True, only the rendering process' extra environment variables will be used. If False (the default behavior), the extra environment variables will be merged with the current environment. More...
 
bool UseProcessTree [get, set]
 If True, further sub-processes started by this ManagedProcess will be tracked and terminated along with it. On Windows, this utilizes Job Objects. Defaults to True. More...
 
string UserName [get, set]
 The user to run as. Only works if RunAsUser is enabled. More...
 

Events

GenericDelegate1< int > CheckExitCodeCallback
 If a function is assigned to this callback, it will be called after the executable has finished running, and can be used to check the exit code. If no function is assigned, the default behavior will be to fail if the executable returns a non-zero exit code. More...
 
GenericDelegate0 InitializeProcessCallback
 If a function is assigned to this callback, it will be called to initialize the process. More...
 
GenericDelegate3< string[], string, string, string > ModifyCommandLineCallback
 If a function is assigned to this callback, it will be called immediately before the executable is run, and can be used to modify the executable command. The function must return a tuple of three strings denoting the executable path, the command arguments, and the startup directory. More...
 
GenericDelegate0 PostRenderTasksCallback
 If a function is assigned to this callback, it will be called after the executable has finished running. More...
 
GenericDelegate0 PreRenderTasksCallback
 If a function is assigned to this callback, it will be called prior to running the executable. More...
 
GenericDelegate0< string > RenderArgumentCallback
 If a function is assigned to this callback, it will be called to return the arguments to be passed to the executable. More...
 
GenericDelegate0 RenderCanceledCallback
 If a function is assigned to this callback, it will be called when the render is canceled. It can be used to perform some cleanup operations. More...
 
GenericDelegate0< string > RenderExecutableCallback
 A function must be assigned to this callback. It should return the executable to be run. If the executable isn't rooted, the current directory will be checked first, followed by all directories in the PATH environment variable. More...
 
GenericDelegate0< string > StartupDirectoryCallback
 If a function is assigned to this callback, it will be called to return the directory that the exectuable should run. More...
 
GenericDelegate0 TimeoutTasksCallback
 If a function is assigned to this callback, it will be called if update timeouts are enabled, and that timeout has passed. More...
 

Detailed Description

A base class for managing a process.

Member Enumeration Documentation

◆ AbortLevel

The different levels when aborting a render.

Enumerator
Minor 

When a minor error occurs, the current task is requeued, but no error report is generated.

Major 

When a major error occurs, the current task is requeued and an error report is generated.

Fatal 

When a fatal error occurs, the current task is failed and an error report is generated.

Success 

When the render is aborted with success, the task is considered complete.

Constructor & Destructor Documentation

◆ ManagedProcess()

FranticX.Processes.ManagedProcess.ManagedProcess ( )

Constructor.

Member Function Documentation

◆ AbortRender() [1/2]

void FranticX.Processes.ManagedProcess.AbortRender ( string  message)

Aborts the render with a Major abort level.

Parameters
messageThe message explaining why the render was aborted.

◆ AbortRender() [2/2]

void FranticX.Processes.ManagedProcess.AbortRender ( string  message,
AbortLevel  level 
)

Aborts the render with the given abort level.

Parameters
messageThe message explaining why the render was aborted.
levelThe abort level.

◆ AddExitCodeToIgnore()

void FranticX.Processes.ManagedProcess.AddExitCodeToIgnore ( int  exitCode)

Adds an exit code that should be ignored.

Parameters
exitCodeThe exit code.

◆ AddPopupHandler() [1/2]

void FranticX.Processes.ManagedProcess.AddPopupHandler ( string  regexTitle,
string  buttons 
)

Adds a popup handler to press one or more buttons when a matching popup is detected.

Parameters
regexTitleThe regular expression used to match the title of the popup.
buttonsThe button to press. To press more than one button, use semicolons to separate the buttons.

◆ AddPopupHandler() [2/2]

void FranticX.Processes.ManagedProcess.AddPopupHandler ( string  regexTitle,
string  regexContent,
string  buttons 
)

Adds a popup handler to press one or more buttons when a matching popup is detected.

Parameters
regexTitleThe regular expression used to match the title of the popup.
regexContentThe regular expression used to match the window content of the popup.
buttonsThe button to press. To press more than one button, use semicolons to separate the buttons.

◆ AddPopupIgnorer() [1/2]

void FranticX.Processes.ManagedProcess.AddPopupIgnorer ( string  regexTitle)

Adds a popup ignorer. If a matching popup is detected, it is ignored. This should not be used on popups that block the rendering process (AddPopupHandler should be used in this case).

Parameters
regexTitleThe regular expression used to match the title of the popup.

◆ AddPopupIgnorer() [2/2]

void FranticX.Processes.ManagedProcess.AddPopupIgnorer ( string  regexTitle,
string  regexContent 
)

Adds a popup ignorer. If a matching popup is detected, it is ignored. This should not be used on popups that block the rendering process (AddPopupHandler should be used in this case).

Parameters
regexTitleThe regular expression used to match the title of the popup.
regexContentThe regular expression used to match the window content of the popup.

◆ AddStdoutHandlerCallback()

RegexHandlerCallback FranticX.Processes.ManagedProcess.AddStdoutHandlerCallback ( string  regexString)

Adds a stdout handler that can be used to handle a matching line of stdout. A RegexHandlerCallback object is returned, and a callback can be assigned to this object's HandleCallback property to handle a matching line of stdout.

Parameters
regexStringThe regular expression used to match a line of stdout.
Returns
The RegexHandlerCallback object.

◆ AddStdoutHandlerEvent()

RegexHandlerCallback FranticX.Processes.ManagedProcess.AddStdoutHandlerEvent ( string  regexString)

DEPRECATED: Use AddStdoutHandlerCallback.

Parameters
regexString
Returns

◆ ClearEnvironmentVariables()

void FranticX.Processes.ManagedProcess.ClearEnvironmentVariables ( )

Clears the extra environment variables for the rendering process.

◆ DetectLoop()

static bool FranticX.Processes.ManagedProcess.DetectLoop ( MethodBase  info)
static

Parameters
info
Returns

◆ EnvironmentVariableExists()

bool FranticX.Processes.ManagedProcess.EnvironmentVariableExists ( string  key)

Checks if the environment with the given key exists.

Parameters
keyThe name of the environment variable.
Returns
True if the variable exists, otherwise False.

◆ GetEnvironmentVariable()

string FranticX.Processes.ManagedProcess.GetEnvironmentVariable ( string  key)

Gets the extra environment variable for the rendering process with the given key. If the variable is not defined, an empty string is returned.

Parameters
keyThe name of the environment variable.
Returns
The value, or an empty string if the variable is not defined.

◆ GetPreviousStdoutLine()

string FranticX.Processes.ManagedProcess.GetPreviousStdoutLine ( )

Gets the previous line of stdout. This should be called from a callback for a stdout handler to get the line before the current one.

Returns
The previous line of stdout.

◆ GetRegexMatch()

string FranticX.Processes.ManagedProcess.GetRegexMatch ( int  index)

Gets the matched text at the given index for the current regular expression. This should be called from a callback for a stdout handler to get a match from the current line being handled.

Parameters
indexThe index. An error will be thrown if the index falls outside the range for the current regular expression.
Returns
The matched text at the specified index.

◆ RedirectStdoutToFile()

void FranticX.Processes.ManagedProcess.RedirectStdoutToFile ( string  filename)

Redirect stdout for this render to the specified file. This should be called from the callback to initialize the process to ensure that all stdout goes to the file.

Parameters
filenameThe name of the file. If the file already exists, it will be overwritten.

◆ ResetProcessAffinity()

void FranticX.Processes.ManagedProcess.ResetProcessAffinity ( )

Resets the affinity settings for the process.

◆ SetEnvironmentVariable()

void FranticX.Processes.ManagedProcess.SetEnvironmentVariable ( string  key,
string  value 
)

Sets extra environment variables for the rendering process only. This will take precedence over a variable in the current environment with the same name.

Parameters
keyThe name of the environment variable.
valueThe value.

◆ SetUpdateTimeout()

void FranticX.Processes.ManagedProcess.SetUpdateTimeout ( int  timeout)

Sets the update timeout. A timeout error will occur if the process goes the specified number of seconds without any stdout being printed out.

Parameters
timeoutThe timeout, in seconds. If less than 0, timeout is disabled (which is the default behavior).

◆ SuppressThisLine()

void FranticX.Processes.ManagedProcess.SuppressThisLine ( )

Suppresses the next line of stdout. This should be called from a callback for a stdout handler to suppress the current line being handled.

Property Documentation

◆ AsynchronousStdout

bool FranticX.Processes.ManagedProcess.AsynchronousStdout
getset

Gets or sets if stdout redirection is asynchronous. This is ignored if StdoutRedirection is disabled. This is also ignored on Windows.

◆ CreateNewConsole

bool FranticX.Processes.ManagedProcess.CreateNewConsole
getset

Gets or sets if a new console should be created.

◆ DebugLogging

bool FranticX.Processes.ManagedProcess.DebugLogging
getset

Gets or sets if debug logging is enabled.

◆ Domain

string FranticX.Processes.ManagedProcess.Domain
getset

The domain when running the process as a different user. This is ignored on Linux and Mac OSX.

◆ FatalPythonErrors

bool FranticX.Processes.ManagedProcess.FatalPythonErrors
getset

Gets or sets if python errors should be treated as fatal errors.

◆ HandleQtPopups

bool FranticX.Processes.ManagedProcess.HandleQtPopups
getset

Gets or sets whether or not the process should handle Qt popups

◆ HandleWindows10Popups

bool FranticX.Processes.ManagedProcess.HandleWindows10Popups
getset

Gets or sets whether or not the process should handle Windows10 popups

◆ HideDosWindow

bool FranticX.Processes.ManagedProcess.HideDosWindow
getset

Gets or sets of the Dos window should be hidden.

◆ ImmediateTermination

bool FranticX.Processes.ManagedProcess.ImmediateTermination
getset

Gets or sets if the process should terminate immediately instead of being allowed to shutdown gracefully.

◆ MaxHandledLineSize

int FranticX.Processes.ManagedProcess.MaxHandledLineSize
getset

Gets or sets the maximum line size that will be handled by the stdout handlers. Set to 0 to disable stdout handling.

◆ Password

string FranticX.Processes.ManagedProcess.Password
getset

The password when running the process as a different user. This is ignored on Linux and Mac OSX.

◆ PopupButtonClasses

string [] FranticX.Processes.ManagedProcess.PopupButtonClasses
getset

Gets or sets the list of class names that the popup handlers considers to be buttons.

◆ PopupHandling

bool FranticX.Processes.ManagedProcess.PopupHandling
getset

Gets or sets if popup handling is enabled.

◆ PopupMaxChildWindows

int FranticX.Processes.ManagedProcess.PopupMaxChildWindows
getset

Gets or sets the maximum number of controls that can be in a popup window. If a popup has more then this, it will not be considered a popup and will be ignored.

◆ PopupTextClasses

string [] FranticX.Processes.ManagedProcess.PopupTextClasses
getset

Gets or sets the list of class names that the popup handlers considers to be text fields.

◆ PreserveEnvironment

bool FranticX.Processes.ManagedProcess.PreserveEnvironment
getset

If true, the environment will be preserved when running the process as another user using 'su' or 'sudo'. This is ignored on Windows.

◆ PressEnterDuringRender

bool FranticX.Processes.ManagedProcess.PressEnterDuringRender
getset

Gets or sets if the Enter button should be pressed shortly after starting the process. This can be useful if the process requires a key press to exit after it finishes running.

◆ ProcessAffinity

int [] FranticX.Processes.ManagedProcess.ProcessAffinity
getset

Gets or sets the affinity for the process (Windows and Linux only). If set to an empty list, the default affinity will be used.

◆ ProcessPriority

ProcessPriorityClass FranticX.Processes.ManagedProcess.ProcessPriority
getset

Gets or sets the process priority class. This should typically be set to ProcessPriorityClass.BelowNormal so that the machine is still interactive during a heavy render.

◆ RunAsUser

bool FranticX.Processes.ManagedProcess.RunAsUser
getset

If true, the process will run as the user specified in UserName.

◆ RunAsUserWithSu

bool FranticX.Processes.ManagedProcess.RunAsUserWithSu
getset

If true, 'su' will be used to run the process as another user instead of 'sudo'. This is ignored on Windows.

◆ SetHomeVariable

bool FranticX.Processes.ManagedProcess.SetHomeVariable
getset

If true, the HOME environment variable will be set to the users home directory when running sudo. Not compatible with su. This is ignored on Windows.

◆ SimulateLogin

bool FranticX.Processes.ManagedProcess.SimulateLogin
getset

If true, 'su' will simulate a login by the user we are running as.

Only applicable on Unix-based systems, and only if RunAsUser and RunAsUserWithSu are true.

◆ StdOutEncoding

string FranticX.Processes.ManagedProcess.StdOutEncoding
getset

Used to specify the name of the Character Encoding that will be used to decode StdOut and StdErr.

If left null/empty, or an invalid/un-supported value is provided, the system default will be used instead.

Refer to the table at https://msdn.microsoft.com/en-us/library/system.text.encoding.aspx for available values.

◆ StdoutHandling

bool FranticX.Processes.ManagedProcess.StdoutHandling
getset

Gets or sets if stdout handling is enabled. This is ignored if StdoutRedirection is disabled.

◆ StdoutRedirection

bool FranticX.Processes.ManagedProcess.StdoutRedirection
getset

Gets or sets if stdout redirection is enabled.

◆ TerminateOnExit

bool FranticX.Processes.ManagedProcess.TerminateOnExit
getset

Gets or sets of the process should be terminated on exit.

◆ UseExtraEnvironmentVariablesOnly

bool FranticX.Processes.ManagedProcess.UseExtraEnvironmentVariablesOnly
getset

If True, only the rendering process' extra environment variables will be used. If False (the default behavior), the extra environment variables will be merged with the current environment.

◆ UseProcessTree

bool FranticX.Processes.ManagedProcess.UseProcessTree
getset

If True, further sub-processes started by this ManagedProcess will be tracked and terminated along with it. On Windows, this utilizes Job Objects. Defaults to True.

◆ UserName

string FranticX.Processes.ManagedProcess.UserName
getset

The user to run as. Only works if RunAsUser is enabled.

Event Documentation

◆ CheckExitCodeCallback

GenericDelegate1<int> FranticX.Processes.ManagedProcess.CheckExitCodeCallback

If a function is assigned to this callback, it will be called after the executable has finished running, and can be used to check the exit code. If no function is assigned, the default behavior will be to fail if the executable returns a non-zero exit code.

◆ InitializeProcessCallback

GenericDelegate0 FranticX.Processes.ManagedProcess.InitializeProcessCallback

If a function is assigned to this callback, it will be called to initialize the process.

◆ ModifyCommandLineCallback

GenericDelegate3<string[], string, string, string> FranticX.Processes.ManagedProcess.ModifyCommandLineCallback

If a function is assigned to this callback, it will be called immediately before the executable is run, and can be used to modify the executable command. The function must return a tuple of three strings denoting the executable path, the command arguments, and the startup directory.

◆ PostRenderTasksCallback

GenericDelegate0 FranticX.Processes.ManagedProcess.PostRenderTasksCallback

If a function is assigned to this callback, it will be called after the executable has finished running.

◆ PreRenderTasksCallback

GenericDelegate0 FranticX.Processes.ManagedProcess.PreRenderTasksCallback

If a function is assigned to this callback, it will be called prior to running the executable.

◆ RenderArgumentCallback

GenericDelegate0<string> FranticX.Processes.ManagedProcess.RenderArgumentCallback

If a function is assigned to this callback, it will be called to return the arguments to be passed to the executable.

◆ RenderCanceledCallback

GenericDelegate0 FranticX.Processes.ManagedProcess.RenderCanceledCallback

If a function is assigned to this callback, it will be called when the render is canceled. It can be used to perform some cleanup operations.

◆ RenderExecutableCallback

GenericDelegate0<string> FranticX.Processes.ManagedProcess.RenderExecutableCallback

A function must be assigned to this callback. It should return the executable to be run. If the executable isn't rooted, the current directory will be checked first, followed by all directories in the PATH environment variable.

◆ StartupDirectoryCallback

GenericDelegate0<string> FranticX.Processes.ManagedProcess.StartupDirectoryCallback

If a function is assigned to this callback, it will be called to return the directory that the exectuable should run.

◆ TimeoutTasksCallback

GenericDelegate0 FranticX.Processes.ManagedProcess.TimeoutTasksCallback

If a function is assigned to this callback, it will be called if update timeouts are enabled, and that timeout has passed.