C++ API reference

This section documents the C++ layer of PyCAPIO directly from the source headers. It is generated by Doxygen and embedded with Breathe, so it stays in sync with the code as long as the Doxygen comments are kept up to date.

Note

If this page is empty, the Doxygen XML has not been generated yet. Run doxygen Doxyfile inside the docs/ directory (or build via the provided Makefile, which does it for you) before building the HTML.

Streaming I/O

enum class IOMode

Stream interpretation used by IOWrapper.

Values:

enumerator Text

Decode reads/writes as str.

enumerator Binary

Treat reads/writes as raw bytes.

template<IOMode Mode>
class IOWrapper

File-like wrapper around a CAPIO stream.

Implements the Python file-object protocol (read, readline, readlines, write, writelines, seek, flush, close, iteration and context-manager support) on top of a CAPIO file descriptor.

The IOMode template parameter selects the element type: Text wrappers return std::string (Python str), while Binary wrappers return pybind11::bytes. The two instantiations are exposed to Python as PyCapioTextIOWrapper and PyCapioBinaryIOWrapper respectively.

Template Parameters:

Mode – Stream interpretation, see IOMode.

Public Functions

inline IOWrapper(const int fd, const uint64_t chunk_size = 16 * 1024)
inline ~IOWrapper()
inline auto write(const std::string &text) const
inline auto writelines(const std::vector<std::string> &lines) const
inline ReturnType read(int64_t size = -1)
inline ReturnType readline()
inline ReturnType next()
inline std::vector<ReturnType> readlines()
inline auto fileno() const
inline void close()
inline auto seek(const int offset, const int whence) const
inline bool closed() const
inline IOWrapper &iter()

Public Static Functions

static inline void flush()

Filesystem helpers

class OsPath

CAPIO-aware replacement for Python’s os.path module.

Each static method mirrors the semantics of the corresponding os.path function. Methods in the libcapio group answer their query through the CAPIO server (so they work on files that live only inside the CAPIO directory); the remaining methods are pure path-string manipulation that match the behaviour of the standard library.

On the Python side this class is exposed as PyCapioPath and installed in place of os.path while a CapioContext is active.

CAPIO-backed queries

These consult the CAPIO server and therefore see files managed by CAPIO.

static bool exists(const std::string &path)

Return true if path exists.

Parameters:

path – Path to test.

static bool isfile(const std::string &path)

Return true if path exists and is a regular file.

Parameters:

path – Path to test.

static bool isdir(const std::string &path)

Return true if path exists and is a directory.

Parameters:

path – Path to test.

static uintmax_t getsize(const std::string &path)

Return the size of path in bytes.

Parameters:

path – File whose size is requested.

Pure path manipulation

String-only helpers that do not touch the filesystem.

static std::string basename(const std::string &path)

Return the final component of path.

static std::string dirname(const std::string &path)

Return everything in path except the final component.

static std::string abspath(const std::string &path)

Return the absolute, normalised form of path.

static std::pair<std::string, std::string> splitext(const std::string &path)

Split path into a (root, extension) pair.

static bool isabs(const std::string &p)

Return true if p is an absolute path.

static std::string normpath(const std::string &p)

Collapse redundant separators and up-level references in p.

static std::string relpath(const std::string &path, const std::string &start = ".")

Return path relative to start.

Parameters:

  • path – Target path.

  • start – Base directory the result is computed against (default “.”).

static double getmtime(const std::string &path)

Return the last-modification time of path as a POSIX timestamp.

static bool samefile(const std::string &p1, const std::string &p2)

Return true if p1 and p2 refer to the same file.

static std::pair<std::string, std::string> split(const std::string &p)

Split p into a (head, tail) pair at the last separator.

static std::string normcase(const std::string &p)

Normalise the case of p (platform dependent).

static std::string realpath(const std::string &path)

Resolve symbolic links in path to a canonical path.

static std::string join(const std::string &path1, const std::string &path2)

Join path1 and path2 with the path separator.

class CapioDirEntry

A single entry produced while scanning a CAPIO directory.

Mirrors the relevant parts of Python’s os.DirEntry. Exposed to Python as DirEntry and yielded by PyCapioScandirWrapper.

Public Functions

CapioDirEntry(const std::filesystem::path &base, const dirent64 &ent)

Construct from a directory base path and a raw dirent64 record.

Parameters:

  • base – Directory that contains the entry.

  • ent – Raw directory record returned by CAPIO.

std::string name() const

Entry name (final path component).

std::string path() const

Full path of the entry (base path joined with the name).

uint64_t inode() const

Inode number of the entry.

bool is_dir(bool follow_symlinks = true) const

Return true if the entry is a directory.

Parameters:

follow_symlinks – Follow symbolic links when resolving the type.

bool is_file(bool follow_symlinks = true) const

Return true if the entry is a regular file.

Parameters:

follow_symlinks – Follow symbolic links when resolving the type.

bool is_symlink() const

Return true if the entry is a symbolic link.

class ScandirIteratorWrapper

Iterator over the contents of a CAPIO directory.

Implements the Python iterator and context-manager protocols, yielding CapioDirEntry objects. Exposed to Python as PyCapioScandirWrapper and used by the scandir / listdir proxies.

Public Functions

explicit ScandirIteratorWrapper(const std::filesystem::path &path)

Open path for scanning.

~ScandirIteratorWrapper()

Close the underlying directory descriptor.

CapioDirEntry next()

Return the next entry, or raise StopIteration when exhausted.

ScandirIteratorWrapper &iter()

Return *this so the object is its own iterator.

void close()

Release the directory descriptor early.

Error handling

class PyCapioException : public std::exception

Exception type raised by the PyCAPIO native layer.

Carries an error message and, when constructed, captures the current Python call stack to make failures that originate inside intercepted I/O easier to diagnose. Surfaced to Python as PyCAPIOException.

Public Functions

explicit PyCapioException(const std::string &error_message)

Construct with a human-readable error message.

Parameters:

error_message – Description of what went wrong.

const char *what() const noexcept override

Return the stored error message.

libcapio entry points

Functions

int bootstrap_capio_server(const std::filesystem::path &CAPIO_DIR, const std::string &CAPIO_WORKFLOW_NAME, const std::string &capio_server_exec_path, const std::string &capio_cl_config, int await_server_timeout_seconds)

Start the CAPIO server process for a workflow and wait until it is ready.

Parameters:

  • CAPIO_DIR – Root directory managed by CAPIO.

  • CAPIO_WORKFLOW_NAME – Logical workflow name reported to CAPIO.

  • capio_server_exec_path – Path or name of the CAPIO server executable.

  • capio_cl_config – Optional path to a CAPIO-CL configuration file.

  • await_server_timeout_seconds – Seconds to wait for the server to be ready.

Returns:

Status code (0 on success).

int libcapio_init(const std::filesystem::path &CAPIO_DIR = ".", const std::string &CAPIO_APP_NAME = CAPIO_DEFAULT_APP_NAME, const std::string &CAPIO_WORKFLOW_NAME = CAPIO_DEFAULT_WORKFLOW_NAME, const std::string &capio_server_exec_path = "capio_server", const std::string &capio_cl_config = "", int await_server_timeout_seconds = 2)

Initialise CAPIO and start or attach to the CAPIO server.

Parameters:

  • CAPIO_DIR – Root directory managed by CAPIO.

  • CAPIO_APP_NAME – Logical application name reported to CAPIO.

  • CAPIO_WORKFLOW_NAME – Logical workflow name reported to CAPIO.

  • capio_server_exec_path – Path or name of the CAPIO server executable.

  • capio_cl_config – Optional path to a CAPIO-CL configuration file.

  • await_server_timeout_seconds – Seconds to wait for the server to be ready.

Returns:

Status code (0 on success).

void libcapio_teardown(bool teardown_server = false)

Tear down CAPIO, optionally stopping the server process.

Parameters:

teardown_server – When true, also shut down the CAPIO server.

int libcapio_open(const char *path, int flags, mode_t mode = 0)

Open a CAPIO-managed file.

Parameters:

  • path – File path inside the CAPIO directory.

  • flags – POSIX open flags (see FILE_MODES on the Python side).

  • mode – Permission bits applied when the file is created.

Returns:

A file descriptor on success.

long libcapio_read(int fd, char *buf, size_t size)

Read up to size bytes from a CAPIO file descriptor.

Parameters:

  • fd – Open CAPIO file descriptor.

  • buf – Destination buffer of at least size bytes.

  • size – Maximum number of bytes to read.

Returns:

The number of bytes read, 0 at EOF, or a negative value on error.

long libcapio_write(int fd, const char *buf, size_t size)

Write size bytes to a CAPIO file descriptor.

Parameters:

  • fd – Open CAPIO file descriptor.

  • buf – Source buffer holding the data to write.

  • size – Number of bytes to write.

Returns:

The number of bytes written, or a negative value on error.

long libcapio_close(int fd)

Close a CAPIO file descriptor.

Parameters:

fd – File descriptor to close.

Returns:

0 on success or a negative value on error.

long libcapio_readdir(int fd, dirent64 *entry)

Read the next directory entry from a CAPIO directory descriptor.

Parameters:

  • fd – Open CAPIO directory descriptor.

  • entry – Output parameter that receives the next entry.

Returns:

A positive value when an entry was read, 0 at the end of the directory, or a negative value on error.

long libcapio_mkdir(const char *path, int mode)

Create a directory inside the CAPIO directory.

Parameters:

  • path – Directory path to create.

  • mode – Permission bits for the new directory.

long libcapio_lseek(int fd, long offset, int whence)

Reposition the offset of a CAPIO file descriptor.

Parameters:

  • fd – Open CAPIO file descriptor.

  • offset – Byte offset relative to whence.

  • whence – Reference point (SEEK_SET, SEEK_CUR or SEEK_END).

Returns:

The resulting absolute offset, or a negative value on error.

long libcapio_stat(const char *path, struct stat *statbuf)

Retrieve metadata for a CAPIO-managed path.

Parameters:

  • path – Path to stat.

  • statbuf – Output parameter that receives the file metadata.

Returns:

0 on success or a negative value on error.

class StartupSemaphore
#include <libcapio.hpp>

RAII guard that serialises CAPIO server startup across processes.

On construction it acquires a per-workflow lock so that only one process bootstraps the CAPIO server for a given workflow; the lock is released on destruction. Evaluating the object in a boolean context reports whether this process is the one responsible for starting the server.

Public Functions

explicit StartupSemaphore(const std::string &workflow_name)

Acquire the startup lock for workflow_name.

Parameters:

workflow_name – Workflow whose startup is being guarded.

~StartupSemaphore()

Release the startup lock.

explicit operator bool() const

Report whether this process should start the CAPIO server.

Returns:

true if this process holds the right to bootstrap the server.

Private Members

int fp

File descriptor backing the lock.

const std::string lock_to_check

Path of the workflow lock file.