Harlequin RIP SDK
Files
RIP Farm Test Tool
RIP Farm: API and Library to split jobs across multiple RIPs

The RIP Farm Test Tool is provided as a source code example demonstrating how to use the RIP Farm API. More...

Files

file  ripfarmtesttool.c
 Implements a RIP Farm Test Tool as an example usage of the libripfarm interface library.
 
file  ripfarmtesttool.h
 Implements a RIP Farm Test Tool as an example usage of the RIP Farm.
 
file  testtooliface.c
 Implements a RIP Farm Test Tool as an example usage of the RIP Farm.
 
file  testtooliface.h
 Implements a RIP Farm Test Tool as an example usage of the RIP Farm.
 
file  testtoolkeyboard.c
 Implements the RIP Farm Test Tool as an example usage of the RIP Farm.
 
file  testtoolsignals.c
 Implements the RIP Farm Test Tool as an example usage of the RIP Farm.
 

Detailed Description

The RIP Farm Test Tool is provided as a source code example demonstrating how to use the RIP Farm API.

The Scalable RIP test tool is an interactive command-based console application that can be used to test the Scalable RIP. It is supplied as buildable source code, so it also provides an example of how to use the libripfarm library for interfacing with the Scalable RIP.

When running a Scalable RIP that the test tool will communicate with, the RIP must be persistent. The simplest way to do this is to specify the -rfin option to the "clrip" application. If you wish to accept input from hot folders the -H option can be used instead to specify the hot folder names.

The test tool provides a keyboard interactive and scriptable mechanism to send commands to the RIP Farm, and receive and log replies from the RIP Farm. It can be used to automate testing of RIP Farms, or to debug or explore the RIP Farm API.

RIP Farm Test Tool commands

The Scalable RIP test tool command line is parsed as a series of space-separated words. Double or single quotation marks can be used to include spaces in a word. Quotation marks can be escaped with a backslash. Each word is terminated by a space or by a newline, so quoted words are joined together if not separated by a space (e.g., "This" "is" is parsed as the single word "This is"). The Scalable RIP test tool commands are:

farmstart
Spawn a Scalable RIP process (if configured), and send a Farm Start message to the Scalable RIP. If the global configuration file has a SpawnBeforeFarmStart section, and inside that there is an Executable key-value pair, the Scalable RIP executable specified will be run. The global configuration is communicated to the Scalable RIP executable. The SpawnBeforeFarmStart dictionary may also contain keys WorkingDirectory and Arguments. The values of these are a string (for WorkingDirectory), giving the current directory in which the Scalable RIP executable will be run, and an array of strings giving the arguments passed to the Scalable RIP executable.
farmstop
Send a Farm Stop message to the Scalable RIP. This will shut down the Scalable RIP.
jobstart id jobname [config] [overrideps] [priority]

Send a Job Start message to start a new job on the Scalable RIP. The job ID and job name are mandatory; all other arguments are optional. If an optional argument is specified, all of the arguments up to it must also be specified (and given empty or default values as necessary). The arguments are:

  • ID. A job number. This should be a non-negative integer. The Scalable RIP cannot have two jobs with the same job number running simultaneously. If the job ID is zero, the Scalable RIP will automatically choose a job number. The job number chosen will be communicated back to the integration API in the Job Starting callback. Note that if job numbers are explicitly chosen (not zero), and jobs submitted from other sources simultaneously (e.g., hot folder), then the job numbers may conflict and produce an error.
  • jobname. The filename of the job.
  • config. The configuration to be used to interpret the job. This will usually be a test config name in the SW/TestConfig directory. However, it may also be an absolute filename, or a PostScript qualified device name such as %configps%TestConfigName.
  • overrideps. The override PostScript used to specify page features, etc. This is optional; however, if the remaining arguments (priority and pages) are to be used, this should be the empty string "".
  • priority. A number giving the priority of the job. This can be used to change the order in which the Scalable RIP processes page ranges from jobs. Higher priority numbers will be processed first. The default priority is 0. Priorities can be negative for low priority jobs.

jobcancel [id]
Send a Job Cancel message to cancel the job number specified. Specifying id zero will cancel all jobs.
jobpause [id]
Send a Job Pause message to pause the job number specified. Specifying id zero will pause all jobs.
jobresume [id]
Send a Job Resume message to resume the job number specified. Specifying id zero will resume all paused jobs.
jobstatus [id]
Request and print status, job and progress information for the job number specified. Specifying id zero will get status for all jobs.
rasterconnect [name]
Open a raster connection to request and handle rasters. Multiple connections may be open at the same time. The optional name will be included in the raster status, showing which client is responsible for requesting and handling a job. A message will be returned giving a connection ID. This connection ID must be used in requests to deliver or handle pages.
rasterdisconnect [connid]
Close the raster connection identified. If a raster connection is closed before handling all rasters for a job, the job is made available for other clients to handle.
rasterstatus [id] [None|Delivered|Ready|Unready|All|Counts]
Request and print status of rasters for all matching jobs and page states. Specifying id zero requests information about all jobs (this is the default if no parameters are specified). Specifying a page state or combination of page states will return detailed information about the rasters in various states in the jobs matched. Regardless of the page state(s) specified, the page counts returned for any matching job (PagesHandled, PagesDelivered, PagesReady and PagesUnready) will reflect the state of the whole job.
rasterrequest connid id [n]
Request delivery of the next n pages for job id (all pages, if n is zero). The pages will be delivered and printed asynchronously, when there are enough pages ready.
rastershandled connid id [n]
Indicates that the first n pages already delivered from job id have been handled, and that the raster manager can forget about them. The raster manager expects to receive a raster's handled call with zero pages to indicate the end of interest in any job for which it has stored rasters.
ripstatus
Request and print status and progress information for all RIPs.
bladestatus
Request and print the status for all blade controllers in the RIP Farm, indicating which RIPs are running, and their status.
bladeshutdown id [--include-controller] [--force]
Request that an identified blade controller is shut down. All Farm RIPs managed by the blade controller will be removed from the RIP Farm.
sleep n
Wait for a specified number of milliseconds before accepting a new command. This is really only useful when scripting, to delay the next command until a job is running or has finished.
exit
Exit the Scalable RIP test tool application. If running a script, this should be the last command in the script.

Press Enter to print the command summary and prompt again.

RIP Farm Test Tool output

The Scalable RIP test tool will print output on the console when certain messages are received from the Scalable RIP. For example, Job Started, Job Completed, and Job Canceling messages will confirm the job information, or report errors such as nonexistent jobs. Raster Deliver and Raster Status Reply will print details of requested raster delivery and status from the raster manager.

RIP Farm Test Tool command line

The Scalable RIP test tool takes several command-line options, which can be used to affect its operation. It can connect to a Scalable RIP running on another machine, it can read a global configuration file for parameters, and it can read a file of commands to set up repeatable scripted tests. Where possible, the long option names are the same as the Scalable RIP option which performs the same task. The options are:

–help
Print the command-line usage information for the RIP Farm test tool.
–version
Print the version of the RIP Farm test tool.
–rfcd directory
Similar to the "clrip" application, this is the directory in which the ripfarm_global.json global configuration file should be found. If the file is not found, sensible defaults will be used.
–cbc address[:port]
IP address of the central blade controller for the Scalable RIP, or the machine hosting the Scalable RIP, and the base port for the RIP Farm. If this is not supplied, the local host (127.0.0.1) and port 9100 are used.
–script file
Read a file of RIP Farm test tool commands and execute them.

RIP Farm Test Tool internals

The following diagram illustrates the architecture of the RIP Farm Test Tool:

Diagrams illustrating thread usage and data flow in the RIP Farm Test Tool
--------------------------------------------------------------------------
1. Initialisation of threads:
+----------------------------------+
+------------------------+ | |
| | | rf_iface_start |
| testtool_run +---------+ - Spawns DFE Interface thread |
| | | by calling message_callback |
+------------+-----------+ | on each reply from RIP farm |
| | |
| +----------------------------------+
|
v
+------------+-----------+ +------------------------+
| | spawns | |
| testtool_reactor +---------> keyboard_worker |
| | | - runs keyboard_loop |
+------------+-----------+ | |
| +------------------------+
|
|
| +----------------------------------+
| | |
| | Register ZeroMQ Event Handlers: |
+-------------------->+ - keyboard_event |
| - farm_reply_handler |
| |
+----------------------------------+
2. Data Flow - Keyboard Input:
+------------------------+ 1 +------------------------+
- keyboard worker | +-------->+ |
thread | keyboard_loop | | relay_keyboard_string |
| [testtoolkeyboard.c] +<--------+ [testtoolkeyboard.c] |
+------------------------+ 6 +------------------------+
^ |
5 | | 2
| v
+------------------------+ 4 +------------------------+
| +-------->+ |
- Main UI thread | process_keyboard_cmd | | keyboard_event |
| [ripfarmtesttool.c] +<--------+ [testtoolkeyboard.c] |
+------------------------+ 3 +------------------------+
3. Data Flow - Replies from the RIP Farm:
+------------------------+ +------------------------+
- DFE Interface | | 1 | |
thread | message_callback +-------->+ relay_message_callback |
| [testtooliface.c] | | [testtoolsignals.c] |
+------------------------+ +-------------+----------+
|
| 2
v
+------------------------+ +-------------+----------+
- Main UI thread | | 3 | |
| process_farm_reply +<--------+ farm_reply_handler |
| [testtooliface.c] | | [testtoolsignals.c] |
+------------------------+ +------------------------+
rf_iface_start
RF_IFACE_CTXT * rf_iface_start(RF_IFACE_PARAMS *params)
Start the DFE Interface reactor.
process_keyboard_cmd
HqBool process_keyboard_cmd(char *cmdline, RF_IFACE_CTXT *iface_ctxt, int *waitms)
Translates lines of keyboard text into rip farm commands by calling the appropriate rf_send_*() libri...
Definition: ripfarmtesttool.c:661
keyboard_loop
void keyboard_loop(RELAY_KEYBOARD_CTXT *kbd_ctxt)
Keyboard commands from stdin are monitored and passed to the test tool reactor via relay_keyboard_str...
Definition: testtoolkeyboard.c:172
relay_keyboard_string
HqBool relay_keyboard_string(char *str, RELAY_KEYBOARD_CTXT *kbd_ctxt, int *waitms)
Relays keyboard strings between the keyboard_worker and main UI threads by sending a messages over a ...
Definition: testtoolkeyboard.c:215
process_farm_reply
void process_farm_reply(RF_FARM_REPLY *farm_reply)
Handles messages from the farm, which have been relayed via message_callback().
Definition: testtooliface.c:267
testtool_run
HqBool testtool_run(const char *cfg_dir, const char *bcip_str)
Start the libripfarm interface and run the application's reactor. Stop the libripfarm interface when ...
Definition: testtooliface.c:616
message_callback
static HqBool message_callback(void *args, RF_FARM_REPLY farm_reply)
Called directly by the libripfarm interface when the RIP farm sends a message.
Definition: testtooliface.c:234
relay_message_callback
HqBool relay_message_callback(FARM_REPLY_CTXT *farm_reply_ctxt, RF_FARM_REPLY *farm_reply)
Relay a message received from the farm to farm_reply_handler() in the main UI thread via a ZeroMQ pip...
Definition: testtoolsignals.c:84
testtool_reactor
HqBool testtool_reactor(struct RF_IFACE_CTXT *iface_ctxt)
Runs the test tool reactor which monitors ZeroMQ messages from both keyboard_worker() and message_cal...
Definition: testtoolsignals.c:228
keyboard_worker
void keyboard_worker(zsock_t *keyboard_pipe, void *arg)
Keyboard strokes from stdin are monitored and passed to the test tool reactor via a ZeroMQ message ov...
Definition: testtoolkeyboard.c:250
keyboard_event
int keyboard_event(zloop_t *loop, zsock_t *socket, void *arg)
Receives the ZeroMQ messages from relay_keyboard_string() via the test tool reactor,...
Definition: testtoolkeyboard.c:291
farm_reply_handler
static int farm_reply_handler(zloop_t *loop, zsock_t *socket, void *arg)
Receives ZeroMQ messages from relay_message_callback() via the test tool reactor, then sends the mess...
Definition: testtoolsignals.c:118

Keyboard input

Lines of text are received in keyboard_loop() and processed in process_keyboard_cmd(). The former runs in the dedicated keyboard_worker thread, whilst the latter runs in the main UI thread. The implementation of passing data between these threads are in testtoolkeyboard.c.

Lines of text are passed between the threads via relay_keyboard_string() and the test tool reactor.

For each line of text, data is sent back to keyboard_loop() in the reverse direction. This communicates two data items for controlling the UI:

The input is scriptable, as determined by the --script command line option.

RIP farm send functions

The rf_send_*() functions (e.g., rf_send_job_start()) are sent in response to the appropriate keyboard input. These C functions are part of the libripfarm interface and used to send one of the messages to the rip farm. Some of these are not currently implemented.

These functions have been wrapped within thin functions in testtooliface.c to isolate them from the UI which is implemented in ripfarmtesttool.c and testtoolkeyboard.c.

RIP farm reply messages

The rip farm sends reply messages in response to the rf_send_*() functions. Messages from the rip farm are passed to the message_callback() interface function, which is implemented by OEM code, but runs in the DFE interface thread. Since that function should never block, the RIP Farm Test Tool relays the message to process_farm_reply() in the main UI thread where it can be handled at leisure. The messages are relayed between the two via relay_message_callback() and the test tool reactor.

The DFE interface thread is started by calling rf_iface_start().

The test tool reactor

This handles events from both the keyboard input and the message_callback() function of the libripfarm interface. Events from both of these sources are sent to the test tool reactor by messages which are dealt with in testtoolsignals.c.

The test tool reactor runs in the main UI thread.

The RIP farm reply handler

process_farm_reply() handles the messages emitted by the farm. The RIP Farm Test Tool uses the rf_extract_*() functions from the libripfarm interface which return a specialised C structure for each message. The RIP Farm Test Tool just prints the content of most of these messages to standard output.

Some of these messages are not currently implemented.

Implementation files

The RIP Farm Test Tool is implemented in several C files, with header files connecting them.

The main entry point file ripfarmtesttool.c performs the argument parsing, startup, and the functions that run in the main command window UI thread. This includes parsing commands, sending requests to the RIP Farm, and processing replies from the RIP Farm to print them to the output. Global Graphics expects that your RIP Farm applications will need to start reactores, send commands, and process replies, but the other functions provided by this file are not relevant.

The file testtooliface.c implements interactions with the libripfarm library. Global Graphics expects that this file would be largely copied in your application. The interactions with the RIP Farm API should be handled by a dedicated thread, handing off messages to other threads so it does not block for any significant duration.

The file testtoolsignals.c implements the inter-thread messaging between the DFE interface, UI threads, and keyboard commands. Global Graphics expects that the contents of the functions in this file would be completely replaced in your applications using a inter-thread communications and a reactor that fits with a framework library used by your application.

The file testtoolkeyboard.c implements the keyboard reader and inter-thread messaging between the keyboard reader and the UI thread. Global Graphics expects that the functions in this file would not be directly relevant to your application, however if you have other sources of input to your DFE application (e.g., a GUI), the general pattern of running a separate thread and messaging the main UI reactor is relevant and may be copied.