zooui.converters.converterrunner module

Process-based converter execution for parallel media conversion.

This module provides functions to run converters in separate processes, avoiding threading conflicts between pyvips and TileManager threads.

The multiprocessing context is chosen automatically:

• ‘fork’: Used when no other threads are running. Fast and clean shutdown.

• ‘spawn’: Used when other threads exist (fork-after-threads is unsafe). This creates a fresh Python interpreter per worker.

The context can be overridden via ZOOUI_MP_CONTEXT environment variable.

zooui.converters.converterrunner._get_safe_context()

Get a multiprocessing context safe for the current thread state.

Defaults to ‘spawn’ because ‘fork’ is unsafe in any process that has or may later create threads (Qt, TileProviders, etc.). The parent’s C-level mutexes (fontconfig, malloc arenas, libvips thread pools) are inherited in locked states by forked children, causing deadlocks.

Python 3.12+ emits a DeprecationWarning when os.fork() is called with multiple threads active. Using ‘spawn’ avoids this entirely — workers start with clean Python interpreters.

‘spawn’ workers are forcefully terminated in shutdown() via child.terminate(), preventing the teardown hangs sometimes associated with spawn-based pools.

The ZOOUI_MP_CONTEXT environment variable can override this default (e.g. ZOOUI_MP_CONTEXT=fork to restore the old behavior).

zooui.converters.converterrunner._run_vips_conversion(infile, outfile, rotation=0, invert_colors=False, black_and_white=False)

Run VipsConverter in a separate process.

Parameters:

• infile – Path to the source image file

• outfile – Path where the converted PPM will be written

• rotation – Rotation angle in degrees (0, 90, 180, or 270)

• invert_colors – Enable color inversion when True

• black_and_white – Enable grayscale conversion when True

Returns:

None on success, error message string on failure

zooui.converters.converterrunner._run_pdf_conversion(infile, outdir)

Run PDFConverter in a separate process.

Parameters:

• infile – Path to the source PDF file

• outdir – Directory where per-page PPM files will be written

Returns:

None on success, error message string on failure

zooui.converters.converterrunner.init(max_workers=2)

Function :

init(max_workers)

Parameters :

max_workersint

• Maximum number of parallel conversion processes (default: 2)

init(max_workers) –> None

Initialize the converter runner with a process pool.

Thread-safe: This function uses a reentrant lock to ensure safe concurrent initialization and shutdown operations.

zooui.converters.converterrunner.shutdown()

Function :

shutdown()

Parameters :

None

shutdown() –> None

Shutdown the process pool executor and terminate any lingering processes.

Thread-safe: This function uses a reentrant lock to ensure safe concurrent initialization and shutdown operations.

zooui.converters.converterrunner._get_executor()

Function :

_get_executor()

Parameters :

None

_get_executor() –> ProcessPoolExecutor

Get or create the process pool executor.

Thread-safe: This function uses a reentrant lock to ensure safe concurrent access to the global executor. The lock allows reentrancy for the init() -> shutdown() -> init() chain that may occur during context changes.

Returns:

The global process pool executor instance

Return type:

ProcessPoolExecutor

zooui.converters.converterrunner.submit_vips_conversion(infile, outfile, rotation=0, invert_colors=False, black_and_white=False)

Submit a VipsConverter job to run in a separate process.

Parameters:

• infile – Path to the source image file

• outfile – Path where the converted PPM will be written

• rotation – Rotation angle in degrees (0, 90, 180, or 270)

• invert_colors – Enable color inversion when True

• black_and_white – Enable grayscale conversion when True

Returns:

A Future object that will contain the conversion result

zooui.converters.converterrunner.submit_pdf_conversion(infile, outdir)

Submit a PDFConverter job to run in a separate process.

Parameters:

• infile – Path to the source PDF file

• outdir – Directory where per-page PPM files will be written

Returns:

A Future object that will contain the conversion result

class zooui.converters.converterrunner.ConversionHandle(future, infile, outpath)

Bases: object

A handle to a running or completed conversion process.

This class wraps a Future and provides a similar interface to the thread-based Converter class, with progress and error properties.

Create a new ConversionHandle.

Parameters:

• future – The Future object from the process pool

• infile – Path to the source file

• outpath – Path to the output directory (for PDF) or output file

property progress

Return the conversion progress.

Since process-based conversion doesn’t support incremental progress, this returns 0.0 while running and 1.0 when done.

property error

Return the error message if conversion failed, None otherwise.

property page_count

Return the number of pages in the converted PDF.

Only available after conversion completes. Returns 0 if the page count could not be determined.

_count_page_files()

Count page_*.ppm files in the output directory.

_check_result()

Check the future result and update error status.

is_alive()

Return True if the conversion is still running.

join(timeout=None)

Wait for the conversion to complete.