(v13) Union device

This page applies to Harlequin v13.1r0 and later; and to Harlequin Core but not Harlequin MultiRIP

The Union device is used to make several PostScript devices appear as if they were one device. It is most useful for filesystem devices, but can be used for other types of devices too. The Union device combines a set of read-only devices with an optional writable device, making them seamlessly appear like one device. Requests to open files, get parameters, read data, etc., are sent to the writable device first, and then down the sequence of readable devices until either the request is met, or the sequence of devices is exhausted. Files that appear on the writable device hide files of the same name on the readable devices; files on higher-priority readable devices hide files of the same name on lower priority readable devices. If an operation modifies a file that does not exist on the writable device but does exist on a readable device, data will be transferred from the readable device to the writable device. If a file is deleted, a special record will be written on the writable device that hides the file from other operations. Filenames are enumerated across all of the devices, excluding filenames marked as deleted. The readable devices are never modified by file operations; only writable device files are modified.

The clrip skin has support for the simplest and most common use of the Union device: using a writable directory for files that change, while keeping the SW directory unmodified. This use case allows multiple simultaneous RIP processes to be started using the same executable and SW directory, but not to interfere with each other because they do not write temporary files in the same place, or see each other's partially completed file writes. The new -W option to clrip specifies a directory to be used to write files that would have been put in the SW directory.

clrip -c Monochrome72dpi -W SW-write job.pdf

RIPs a PDF job, using the normal SW folder, but writing %os% and temporary files into the directory SW-write, relative to the current directory. Note that the SWwrite directory stores a persistent state of the modified and written files. If used by a subsequent invocation of the RIP, the state will appear as it did when the previous RIP invocation quit.

clrip -c Monochrome72dpi -W C:\temp\write1 job.pdf

RIPs a PDF job, using the normal SW folder, but writing %os% and temporary files into an absolute directory path.

clrip -c Monochrome72dpi -W "%ram%" job.pdf

RIPs a PDF job, using the normal SW folder, but writing %os% and temporary files into a RAM filesystem. All file changes to SW made during the RIP instance will be forgotten on exit. This usage is not recommended for production use, because temporary files can become very large, and can consume all the system RAM.

When running multiple RIP instances, each RIP should specify a different writable directory using -W. Directories may be created empty before the first use, and may either be re-used without modification, or cleared out between subsequent invocations, depending on the your use case.

The Union device is configured through two device parameters:

/Read [ (%device%prefix)... ]

An array of one or more underlying readable devices. The devices may be specified as a device name only, or a device with a prefix. Names referenced on the Union device are accessed on the readable devices by appending the name to this device and prefix. While this device and prefix combination usually refers to a directory on the readable device, it does not need to. It may be an arbitrary partial path on the readable device. The first device in the array has the highest priority, files on it will hide files with the same name on devices later in the array.

/Write (%device%prefix)

An optional writable device and prefix. This is the device prefix used to write files that are modified or created on the Union device. This may be set to an empty string (), in which case the Union device will refuse all write operations.

NOTE:   You are cautioned not to modify the Union device's /Read or /Write parameters while there are files open on the device. The same parameters can be set, however, so currentdevparams setdevparams will succeed.

The underlying devices for the Union device need not be enabled nor searchable for the union to be enabled or searchable. It is indeed preferable that they have /Enable false and /SearchOrder -1, so that they are not directly accessed by PostScript file operations. The /Enable and /Searchable (or /SearchOrder ) keys of the Union device itself control access to the entire collection.

NOTE:   It is important that only one instance of a Union device maps the same writable device and prefix. The Union device caches some information in memory, so if two devices instances are created referring to the same writable device, they will have inconsistent views of the filesystem state. Using the Prefix device to map sub-trees of a filesystem is an important tool to ensure that there are not conflicting instances of the Union device.