Stopping Command Line Helix Producer with Signals

# Sending Signals to the Command Line Application

Last Updated: 2004-03-16

This document describes how to send a stop signal to a running instance of the command line application.

Signals are notifications sent to a process in order to notify it of important events. The Producer command line application accepts signals sent from other applications running on the same machine to end the current encoding session. Signals are supported by Producer on Windows and Linux but in slightly different ways as described below.

Producer supports two types of signals. They are:

- Stop - Stop the current encode and save the resulting RealMedia files (some time may be required to merge SureStream files).
- Cancel - Stop the current encode without saving files and delete all temporary files. Canceling a job results in no output!

Stop and cancel signals have the following effect on the current encoding session:

- Stop or cancel signals can be sent to the command line application for live capture input as well as file to file encodes.
- There is no effective difference between a stop or a cancel signal for broadcast only outputs.
- For file outputs, a cancel signal results in no output.
- For file to file encodes, the portion of the input file that was already encoded when the stop signal is received is written to disk.
- If a stop signal is received during the analysis pass of a 2-pass encode, no output results.
- If a stop signal is received during the merging process (merging is when encoding is complete and multiple rates of a SureStream file are being merged) then the merging process is completed as normal with no effect on the output file.

The remaining sections describe how to generate a stop or cancel signal and identify which running instance of the command line application to send that signal to.

## Sending a Stop Signal to Producer on Linux:

On UNIX the command line application listens and responds to signals. Signals are notifications sent to a process in order to notify it of important events. Signals are classified by name or number. The Signal Name or Signal Number can be used as an argument the kill command on UNIX to remotely send a signal to a running Producer command line instance.

The kill command takes two arguments, the signal name or number and the process ID for which to send the signal to. Following is the syntax for the kill command:

>     kill <signal> <process_id>

The following defines the signals that the command line application responds to.

Signal Name | Signal # | Action
SIGINT | 2 | Stop
SIGTERM | 15 | Stop
SIGQUIT | 3 | Cancel
SIGABRT | 6 | Cancel

Note: SIGHUP is not trapped by the command line application and no action results from sending a SIGHUP to the command line application. Most applications interpret a SIGHUP as a request to re-read configuration settings. This type of behavior is not implemented in the Producer command line application.

The second argument to the kill command is the process ID. A single instance of Producer runs under several process IDs but only one of these will accept a signal. To identify the correct Process ID to send a signal to, use the -pid option to get the process ID as follows:

>     producer -ac 0 -o out.rm -pid /tmp/producer.pid

To send a stop signal to Producer, use the kill command with a SIGINT signal as follows:

>     kill -SIGINT $(cat /tmp/producer.pid)

To send a cancel signal to Producer, use the kill command with a SIGQUIT signal as follows:

>     kill -SIGQUIT $(cat /tmp/producer.pid)

### Programmatically sending signals on Linux

On UNIX the kill function can be used to send a signal to an application from a C or C++ program. The kill function in UNIX allows events to be generated by a C program and sent to a running command line instance by process ID. The Introduction To Unix Signals Programming (http://users.actcom.co.il/~choo/lupg/tutorials/signals/signals-programming.html) covers this in more detail.

A sample utility that sends signals to Producer is available in source and binary format in the samples/utilities/producer_signal_generator directory of Producer. The source code is written to compile on both Windows and Linux without modifications. Comments in the source code provide instructions for how to compile it on either platform. The package includes a compiled executable for Windows and Linux that can be used as-is or modified and recompiled and distributed freely.

The usage for the sample producer signal generator is:

>     Usage: signalproducer {-p <PID> | -P <PIDFILE>} [-a <stop|cancel>] [-q]

## Sending a Stop Signal to Producer on Windows

On Windows the command line application listens for window messages sent to Producer's window handle. When the Producer command line application starts, it registers a window handle based on the process ID (PID). The PID can then be used to send a stop or cancel request to a running instance of the command line application as long as one has the PID.

Windows does not have the equivalent of the kill command on Linux. To send a signal to the command line application on Windows, use the sample command line utility available in source and binary format below.

The usage for the sample producer signal generator (signalproducer.exe) utility is:

>     Usage: signalproducer.exe {-p <PID> | -P <PIDFILE>} [-a <stop|cancel>] [-q]

As shown above, this utility accepts a process ID as input and the type of signal to send to a running instance of the command line application. The PID file can be obtained from the Windows Task Manager or the command line application can be told to record its PID to a file at start up.

To record the command line application PID to file at start up use the -pid command line option as follows:

>     producer -ac 0 -o out.rm -pid "c:\pid.txt"

To send a signal to the running instance of the Producer use signalproducer.exe available in Producer Signal Generator Sample as follows:

>     signalproducer.exe -P c:\pid.txt

This command accepts a filename which identifies the file written by the Producer using the -pid option above.

Note: You can also just pass the PID# directly using a lower case '-p'. To get the PID# on windows, read the PID for producer.exe from the Windows Task Manager.

### Programmatically sending signals on Windows

A sample utility that sends signals to Producer is available in source and binary format in the samples/utilities/producer_signal_generator directory of Producer. The source code is written to compile on both Windows and Linux without modifications. Comments in the source code provide instructions for how to compile it on either platform. The package includes a compiled executable for Windows and Linux that can be used as-is or modified and recompiled and distributed freely.