zooui.tilesystem.tiler.tilerrunner module

Process-based tiling execution for parallel image tiling.

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

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.tilesystem.tiler.tilerrunner._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.tilesystem.tiler.tilerrunner._run_tiling(infile, media_id=None, filext='jpg', tilesize=256)

Run Tiler in a separate process.

Parameters:

• infile – Path to the source PPM file

• media_id – Media identifier for tile storage (defaults to infile)

• filext – Tile file extension (‘jpg’ or ‘png’)

• tilesize – Tile size in pixels

Returns:

None on success, error message string on failure

zooui.tilesystem.tiler.tilerrunner.init(max_workers=4)

Function :

init(max_workers)

Parameters :

max_workersint

• Maximum number of parallel tiling processes (default: 4)

init(max_workers) –> None

Initialize the tiler runner with a process pool.

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

zooui.tilesystem.tiler.tilerrunner.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.tilesystem.tiler.tilerrunner._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.tilesystem.tiler.tilerrunner.submit_tiling(infile, media_id=None, filext='jpg', tilesize=256)

Submit a tiling job to run in a separate process.

Parameters:

• infile – Path to the source PPM file

• media_id – Media identifier for tile storage (defaults to infile)

• filext – Tile file extension (‘jpg’ or ‘png’)

• tilesize – Tile size in pixels

Returns:

A Future object that will contain the tiling result

class zooui.tilesystem.tiler.tilerrunner.TilingHandle(future, infile, media_id=None)

Bases: object

A handle to a running or completed tiling process.

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

Create a new TilingHandle.

Parameters:

• future – The Future object from the process pool

• infile – Path to the source file

• media_id – Media identifier for tile storage

property progress

Return the tiling progress.

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

property error

Return the error message if tiling failed, None otherwise.

_check_result()

Check the future result and update error status.

is_alive()

Return True if the tiling is still running.

join(timeout=None)

Wait for the tiling to complete.