"""Named-pipe helpers for the capture <-> display H.264 sidecar.

Linux fifos deadlock if one side opens O_RDONLY and the other O_WRONLY
before either has a partner. Opening O_RDWR in the parent first makes
filesink/filesrc open() return immediately.
"""
from __future__ import annotations

import os
import stat


def hold_fifo(path: str, mode: int = 0o644) -> int:
    """Create `path` as a fifo if needed and open it O_RDWR | O_NONBLOCK.

    Do not unlink an existing fifo: that splits the inode from any process
    already blocked in open() and recreates the deadlock.
    """
    directory = os.path.dirname(path)
    if directory:
        os.makedirs(directory, exist_ok=True)
    try:
        st = os.stat(path)
        if not stat.S_ISFIFO(st.st_mode):
            os.unlink(path)
            os.mkfifo(path, mode)
    except FileNotFoundError:
        os.mkfifo(path, mode)
    return os.open(path, os.O_RDWR | os.O_NONBLOCK)