Platform-agnostic system utility functions. More...

Functions
VLINK_EXPORT std::string	get_app_path () noexcept
	Returns the absolute path of the running executable.
VLINK_EXPORT std::string	get_app_dir () noexcept
	Returns the directory containing the running executable.
VLINK_EXPORT std::string	get_app_name () noexcept
	Returns the file name of the running executable (without directory prefix).
VLINK_EXPORT std::string	get_host_name () noexcept
	Returns the host name of the current machine.
VLINK_EXPORT int32_t	get_pid () noexcept
	Returns the process ID of the current process.
VLINK_EXPORT std::string	get_pid_str () noexcept
	Returns the process ID of the current process as a decimal string.
VLINK_EXPORT std::string	get_tmp_dir () noexcept
	Returns the platform-specific temporary directory path.
VLINK_EXPORT std::string	get_env (const std::string &key, const std::string &default_value="") noexcept
	Reads the value of an environment variable.
VLINK_EXPORT bool	set_env (const std::string &key, const std::string &value, bool force=true) noexcept
	Sets or updates an environment variable.
VLINK_EXPORT bool	unset_env (const std::string &key) noexcept
	Removes an environment variable.
VLINK_EXPORT std::vector< std::string >	get_all_ipv4_address (bool filter_available=false) noexcept
	Returns all IPv4 addresses assigned to local network interfaces.
VLINK_EXPORT std::vector< std::string >	get_all_ipv6_address (bool filter_available=false) noexcept
	Returns all IPv6 addresses assigned to local network interfaces.
VLINK_EXPORT std::string	get_interface_name_by_ipv4 (const std::string &ipv4) noexcept
	Returns the network interface name that owns a given IPv4 address.
VLINK_EXPORT std::string	get_interface_name_by_ipv6 (const std::string &ipv6) noexcept
	Returns the network interface name that owns a given IPv6 address.
VLINK_EXPORT std::vector< std::string >	get_dds_default_address (bool filter_available=false, int max_count=5) noexcept
	Returns suitable IPv4 addresses for use as DDS participant unicast locators.
VLINK_EXPORT bool	check_singleton (const std::string &program_name="") noexcept
	Checks that only one instance of the process is running (singleton guard).
VLINK_EXPORT bool	wait_for_device (const std::string &path, int timeout_ms, int poll_ms=50) noexcept
	Blocks until a file-system path appears or the timeout elapses.
VLINK_EXPORT void	yield_cpu () noexcept
	Emits a CPU pause/yield hint to reduce bus contention in busy-wait loops.
VLINK_EXPORT void	set_console_utf8_output () noexcept
	Configures the Windows console for UTF-8 output.
VLINK_EXPORT bool	set_thread_name (const std::string &name, std::thread *thread=nullptr) noexcept
	Sets the OS-level name of a thread for debugging tools (e.g., gdb, perf).
VLINK_EXPORT bool	set_thread_priority (int priority_level, int policy=-1, std::thread *thread=nullptr) noexcept
	Sets the scheduling policy and priority of a thread.
VLINK_EXPORT bool	set_thread_stick (uint32_t core_mask, std::thread *thread=nullptr) noexcept
	Pins a thread to a set of CPU cores specified by a bitmask.
VLINK_EXPORT uint64_t	get_native_thread_id () noexcept
	Returns the native OS thread identifier of the calling thread.
VLINK_EXPORT void	register_terminate_signal (std::function< void(int)> &&callback, bool is_async=false, bool pass_through=false) noexcept
	Registers a callback for graceful termination signals (SIGTERM, SIGINT, etc.).
VLINK_EXPORT void	register_crash_signal (std::function< void(int)> &&callback) noexcept
	Registers a callback for crash signals (SIGSEGV, SIGABRT, SIGFPE, SIGBUS, etc.).
VLINK_EXPORT void	start_detect_keyboard (std::function< void(const std::string &key)> &&callback=nullptr, int poll_ms=20) noexcept
	Starts a background thread that detects keyboard input.
VLINK_EXPORT void	stop_detect_keyboard () noexcept
	Stops the keyboard detection thread started by `start_detect_keyboard()`.
VLINK_EXPORT std::pair< int, int >	get_terminal_size () noexcept
	Returns the current terminal window dimensions.
VLINK_EXPORT double	get_cpu_usage () noexcept
	Returns the current CPU usage of the process as a percentage.
VLINK_EXPORT double	get_memory_usage () noexcept
	Returns the resident set size (RSS) of the process as a percentage of total RAM.
VLINK_EXPORT bool	is_process_running (const std::string &process_name) noexcept
	Checks whether a process with the given name is currently running.
VLINK_EXPORT int32_t	get_timezone_diff () noexcept
	Returns the local timezone offset from UTC in seconds.
VLINK_EXPORT std::string	get_machine_id () noexcept
	Returns a unique identifier for the current machine.
VLINK_EXPORT void	try_release_sys_memory () noexcept
	Hints to the OS that any unreferenced cached memory pages can be released.

Detailed Description

Platform-agnostic system utility functions.

Function Documentation

◆ check_singleton()

VLINK_EXPORT bool vlink::Utils::check_singleton ( const std::string & program_name = "" )

nodiscardnoexcept

Checks that only one instance of the process is running (singleton guard).

Uses a lock file or named semaphore to ensure mutual exclusion. Returns false if another instance is already running.

Parameters

program_name Program name used for the lock. Defaults to the executable name.

Returns: true if this is the only running instance.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_all_ipv4_address()

VLINK_EXPORT std::vector< std::string > vlink::Utils::get_all_ipv4_address ( bool filter_available = false )

nodiscardnoexcept

Returns all IPv4 addresses assigned to local network interfaces.

Parameters

filter_available If true, only return addresses on interfaces that are UP. Default: false.

Returns: Vector of dotted-decimal IPv4 address strings.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_all_ipv6_address()

VLINK_EXPORT std::vector< std::string > vlink::Utils::get_all_ipv6_address ( bool filter_available = false )

nodiscardnoexcept

Returns all IPv6 addresses assigned to local network interfaces.

Parameters

filter_available If true, only return addresses on interfaces that are UP. Default: false.

Returns: Vector of IPv6 address strings.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_app_dir()

VLINK_EXPORT std::string vlink::Utils::get_app_dir ( )

nodiscardnoexcept

Returns the directory containing the running executable.

Returns: Directory path (without trailing slash), or empty string on failure.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_app_name()

VLINK_EXPORT std::string vlink::Utils::get_app_name ( )

nodiscardnoexcept

Returns the file name of the running executable (without directory prefix).

Returns: Executable name, or empty string on failure.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_app_path()

VLINK_EXPORT std::string vlink::Utils::get_app_path ( )

nodiscardnoexcept

Returns the absolute path of the running executable.

Returns: Full file-system path, or empty string on failure.

◆ get_cpu_usage()

VLINK_EXPORT double vlink::Utils::get_cpu_usage ( )

nodiscardnoexcept

Returns the current CPU usage of the process as a percentage.

Computes (user_time + kernel_time) / elapsed_time * 100. The value is a snapshot since the last call and may return 0 on the first invocation.

Returns: CPU usage in the range [0.0, 100.0 * num_cpus].

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_dds_default_address()

VLINK_EXPORT std::vector< std::string > vlink::Utils::get_dds_default_address	(	bool	filter_available = false,
		int	max_count = 5 )

nodiscardnoexcept

Returns suitable IPv4 addresses for use as DDS participant unicast locators.

Filters out loopback and link-local addresses, preferring routable unicast addresses.

Parameters

filter_available	If `true`, only return addresses on UP interfaces. Default: `false`.
max_count	Maximum number of addresses to return. Default: 5.

Returns: Vector of selected IPv4 address strings.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_env()

VLINK_EXPORT std::string vlink::Utils::get_env	(	const std::string &	key,
		const std::string &	default_value = "" )

nodiscardnoexcept

Reads the value of an environment variable.

Parameters

key	Name of the environment variable.
default_value	Value returned if the variable is not set. Default: empty string.

Returns: Environment variable value, or default_value if not found.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_host_name()

VLINK_EXPORT std::string vlink::Utils::get_host_name ( )

nodiscardnoexcept

Returns the host name of the current machine.

Returns: Host name as reported by gethostname(), or empty string on failure.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_interface_name_by_ipv4()

VLINK_EXPORT std::string vlink::Utils::get_interface_name_by_ipv4 ( const std::string & ipv4 )

nodiscardnoexcept

Returns the network interface name that owns a given IPv4 address.

Parameters

ipv4	Dotted-decimal IPv4 address to look up.

Returns: Interface name (e.g., "eth0"), or empty string if not found.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_interface_name_by_ipv6()

VLINK_EXPORT std::string vlink::Utils::get_interface_name_by_ipv6 ( const std::string & ipv6 )

nodiscardnoexcept

Returns the network interface name that owns a given IPv6 address.

Parameters

ipv6	IPv6 address string to look up.

Returns: Interface name, or empty string if not found.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_machine_id()

VLINK_EXPORT std::string vlink::Utils::get_machine_id ( )

nodiscardnoexcept

Returns a unique identifier for the current machine.

On Linux, reads /etc/machine-id. On other platforms a platform-specific identifier is used.

Returns: Machine ID string, or empty string on failure.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_memory_usage()

VLINK_EXPORT double vlink::Utils::get_memory_usage ( )

nodiscardnoexcept

Returns the resident set size (RSS) of the process as a percentage of total RAM.

Returns: Memory usage percentage in the range [0.0, 100.0].

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_native_thread_id()

VLINK_EXPORT uint64_t vlink::Utils::get_native_thread_id ( )

nodiscardnoexcept

Returns the native OS thread identifier of the calling thread.

Returns pthread_self() on POSIX or GetCurrentThreadId() on Windows. The value can be used with profiling tools or for thread identification in logs.

Returns: Native thread ID.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_pid()

VLINK_EXPORT int32_t vlink::Utils::get_pid ( )

nodiscardnoexcept

Returns the process ID of the current process.

Returns: Process ID (PID), or -1 on failure.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_pid_str()

VLINK_EXPORT std::string vlink::Utils::get_pid_str ( )

nodiscardnoexcept

Returns the process ID of the current process as a decimal string.

Returns: PID string, or empty string on failure.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_terminal_size()

VLINK_EXPORT std::pair< int, int > vlink::Utils::get_terminal_size ( )

nodiscardnoexcept

Returns the current terminal window dimensions.

Returns: A pair {columns, rows}. Returns {0, 0} on failure or if not a tty.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_timezone_diff()

VLINK_EXPORT int32_t vlink::Utils::get_timezone_diff ( )

nodiscardnoexcept

Returns the local timezone offset from UTC in seconds.

For example, UTC+8 returns 28800, UTC-5 returns -18000.

Returns: Timezone offset in seconds.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_tmp_dir()

VLINK_EXPORT std::string vlink::Utils::get_tmp_dir ( )

nodiscardnoexcept

Returns the platform-specific temporary directory path.

Returns /tmp on Linux/macOS, TEMP% on Windows, or the equivalent on other platforms.

Returns: Temporary directory path, or empty string on failure.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ is_process_running()

VLINK_EXPORT bool vlink::Utils::is_process_running ( const std::string & process_name )

nodiscardnoexcept

Checks whether a process with the given name is currently running.

Parameters

process_name Executable name to search for (without path).

Returns: true if at least one process with that name is running.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ register_crash_signal()

VLINK_EXPORT void vlink::Utils::register_crash_signal ( std::function< void(int)> && callback )

noexcept

Registers a callback for crash signals (SIGSEGV, SIGABRT, SIGFPE, SIGBUS, etc.).

Useful for dumping logs or state before an unrecoverable crash. The callback should be async-signal-safe or very short.

Parameters

callback Callback invoked with the signal number when a crash signal fires.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ register_terminate_signal()

VLINK_EXPORT void vlink::Utils::register_terminate_signal	(	std::function< void(int)> &&	callback,
		bool	is_async = false,
		bool	pass_through = false )

noexcept

Registers a callback for graceful termination signals (SIGTERM, SIGINT, etc.).

On POSIX, installs a sigaction handler for SIGTERM and SIGINT. The callback receives the signal number as its argument.

Parameters

callback	Callback invoked when a termination signal arrives.
is_async	If `true`, the callback runs asynchronously in a dedicated thread. Default: `false` (synchronous in the signal context).
pass_through	If `true`, re-raise the signal after the callback returns so that the default OS behaviour (core dump, etc.) also occurs. Default: `false`.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_console_utf8_output()

VLINK_EXPORT void vlink::Utils::set_console_utf8_output ( )

noexcept

Configures the Windows console for UTF-8 output.

Calls SetConsoleOutputCP(CP_UTF8) on Windows. No-op on other platforms.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_env()

VLINK_EXPORT bool vlink::Utils::set_env	(	const std::string &	key,
		const std::string &	value,
		bool	force = true )

noexcept

Sets or updates an environment variable.

Parameters

key	Name of the environment variable.
value	New value.
force	If `true`, overwrite an existing variable. Default: `true`.

Returns: true on success.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_thread_name()

VLINK_EXPORT bool vlink::Utils::set_thread_name	(	const std::string &	name,
		std::thread *	thread = nullptr )

noexcept

Sets the OS-level name of a thread for debugging tools (e.g., gdb, perf).

Parameters

name	Thread name string (max 15 characters on Linux due to `pthread_setname_np`).
thread	Thread to rename, or `nullptr` for the calling thread. Default: `nullptr`.

Returns: true on success.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_thread_priority()

VLINK_EXPORT bool vlink::Utils::set_thread_priority	(	int	priority_level,
		int	policy = -1,
		std::thread *	thread = nullptr )

noexcept

Sets the scheduling policy and priority of a thread.

On Linux, wraps pthread_setschedparam. Requires appropriate CAP_SYS_NICE or RLIMIT_RTPRIO permissions for real-time policies.

Parameters

priority_level	Scheduling priority (policy-dependent range).
policy	Scheduling policy (e.g., `SCHED_FIFO`, `SCHED_RR`, `SCHED_OTHER`). Pass -1 to keep the current policy. Default: -1.
thread	Thread to configure, or `nullptr` for the calling thread. Default: `nullptr`.

Returns: true on success.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_thread_stick()

VLINK_EXPORT bool vlink::Utils::set_thread_stick	(	uint32_t	core_mask,
		std::thread *	thread = nullptr )

noexcept

Pins a thread to a set of CPU cores specified by a bitmask.

Wraps pthread_setaffinity_np on Linux. Bit i of core_mask corresponds to core i. For example, core_mask == 0b0101 pins to cores 0 and 2.

Parameters

core_mask	Bitmask of CPU cores (bit 0 = core 0).
thread	Thread to pin, or `nullptr` for the calling thread. Default: `nullptr`.

Returns: true on success.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ start_detect_keyboard()

VLINK_EXPORT void vlink::Utils::start_detect_keyboard	(	std::function< void(const std::string &key)> &&	callback = nullptr,
		int	poll_ms = 20 )

noexcept

Starts a background thread that detects keyboard input.

Polls stdin every poll_ms milliseconds for a key press. When a key is detected, callback is invoked with the key name as a string (e.g., "enter", "q"). Stop the detector with stop_detect_keyboard().

Parameters

callback	Callback invoked with the key name, or `nullptr` to ignore. Default: `nullptr`.
poll_ms	Polling interval in milliseconds. Default: 20.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ stop_detect_keyboard()

VLINK_EXPORT void vlink::Utils::stop_detect_keyboard ( )

noexcept

Stops the keyboard detection thread started by start_detect_keyboard().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ try_release_sys_memory()

VLINK_EXPORT void vlink::Utils::try_release_sys_memory ( )

noexcept

Hints to the OS that any unreferenced cached memory pages can be released.

On Linux calls malloc_trim(0) to return freed memory from the glibc heap to the OS. On other platforms this is a no-op.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unset_env()

VLINK_EXPORT bool vlink::Utils::unset_env ( const std::string & key )

noexcept

Removes an environment variable.

Parameters

key	Name of the variable to unset.

Returns: true on success.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ wait_for_device()

VLINK_EXPORT bool vlink::Utils::wait_for_device	(	const std::string &	path,
		int	timeout_ms,
		int	poll_ms = 50 )

noexcept

Blocks until a file-system path appears or the timeout elapses.

Polls the path every poll_ms milliseconds. Useful for waiting for a device node (e.g., /dev/video0) to become available at startup.

Parameters

path	File-system path to poll.
timeout_ms	Maximum wait time in milliseconds.
poll_ms	Polling interval in milliseconds. Default: 50.

Returns: true if the path appeared within the timeout; false on timeout.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ yield_cpu()

void vlink::Utils::yield_cpu ( )

inlinenoexcept

Emits a CPU pause/yield hint to reduce bus contention in busy-wait loops.

Details.

Issues the most efficient idle instruction for the target:

x86/x86-64: PAUSE
ARMv7/AArch64: YIELD
RISC-V: fence hint (.word 0x0100000f)
Fallback: std::this_thread::yield()

This function is always inlined and has zero call overhead.

Here is the caller graph for this function:

Functions

Detailed Description

Function Documentation

◆ check_singleton()

◆ get_all_ipv4_address()

◆ get_all_ipv6_address()

◆ get_app_dir()

◆ get_app_name()

◆ get_app_path()

◆ get_cpu_usage()

◆ get_dds_default_address()

◆ get_env()

◆ get_host_name()

◆ get_interface_name_by_ipv4()

◆ get_interface_name_by_ipv6()

◆ get_machine_id()

◆ get_memory_usage()

◆ get_native_thread_id()

◆ get_pid()

◆ get_pid_str()

◆ get_terminal_size()

◆ get_timezone_diff()

◆ get_tmp_dir()

◆ is_process_running()

◆ register_crash_signal()

◆ register_terminate_signal()

◆ set_console_utf8_output()

◆ set_env()

◆ set_thread_name()

◆ set_thread_priority()

◆ set_thread_stick()

◆ start_detect_keyboard()

◆ stop_detect_keyboard()

◆ try_release_sys_memory()

◆ unset_env()

◆ wait_for_device()

◆ yield_cpu()