Portable host-system utility functions. More...

Functions
VLINK_EXPORT std::string	get_app_path () noexcept
	Returns the absolute path of the executable that is currently running. More...

VLINK_EXPORT std::string	get_app_dir () noexcept
	Returns the directory portion of the executable's absolute path. More...

VLINK_EXPORT std::string	get_app_name () noexcept
	Returns the file-name portion of the executable's absolute path. More...

VLINK_EXPORT std::string	get_host_name () noexcept
	Returns the local machine's host name as reported by the operating system. More...

VLINK_EXPORT int32_t	get_pid () noexcept
	Returns the process identifier of the calling process. More...

VLINK_EXPORT std::string	get_pid_str () noexcept
	Returns the process identifier of the calling process as a decimal string. More...

VLINK_EXPORT std::string	get_tmp_dir () noexcept
	Returns a path suitable for short-lived temporary files. More...

VLINK_EXPORT std::string	get_env (const std::string &key, const std::string &default_value="") noexcept
	Reads the current value of an environment variable. More...

VLINK_EXPORT bool	set_env (const std::string &key, const std::string &value, bool force=true) noexcept
	Sets or updates an environment variable. More...

VLINK_EXPORT bool	unset_env (const std::string &key) noexcept
	Removes an environment variable. More...

VLINK_EXPORT bool	is_ignored_iface_name (const char *name) noexcept
	Returns whether an interface name is treated as virtual/tunnel-only by address discovery. More...

VLINK_EXPORT std::vector< std::string >	get_all_ipv4_address (bool filter_available=false) noexcept
	Returns every IPv4 address bound to a local network interface. More...

VLINK_EXPORT std::vector< std::string >	get_all_ipv6_address (bool filter_available=false) noexcept
	Returns every IPv6 address bound to a local network interface. More...

VLINK_EXPORT std::string	get_interface_name_by_ipv4 (const std::string &ipv4) noexcept
	Returns the interface name that owns a given IPv4 address. More...

VLINK_EXPORT std::string	get_interface_name_by_ipv6 (const std::string &ipv6) noexcept
	Returns the interface name that owns a given IPv6 address. More...

VLINK_EXPORT std::vector< std::string >	get_dds_default_address (bool filter_available=false, int max_count=5) noexcept
	Selects IPv4 addresses suitable as DDS participant unicast locators. More...

VLINK_EXPORT bool	check_singleton (const std::string &program_name="") noexcept
	Provides a singleton mutual-exclusion check for a program name. More...

VLINK_EXPORT bool	wait_for_device (const std::string &path, int timeout_ms, int poll_ms=50) noexcept
	Polls a filesystem path until it exists or a timeout expires. More...

VLINK_EXPORT void	yield_cpu () noexcept
	Emits the most efficient CPU pause/yield hint for the host ISA. More...

VLINK_EXPORT void	set_console_utf8_output () noexcept
	Sets the Windows console output code page to UTF-8. More...

VLINK_EXPORT bool	set_thread_name (const std::string &name, std::thread *thread=nullptr) noexcept
	Sets the OS-visible name of a thread so debug tools display it. More...

VLINK_EXPORT bool	set_thread_priority (int priority_level, int policy=-1, std::thread *thread=nullptr) noexcept
	Updates the scheduling policy and priority of a thread. More...

VLINK_EXPORT bool	set_thread_stick (uint32_t core_mask, std::thread *thread=nullptr) noexcept
	Pins a thread to a set of CPU cores expressed as a bitmask. More...

VLINK_EXPORT uint64_t	get_native_thread_id () noexcept
	Returns the native OS thread identifier of the calling thread. More...

VLINK_EXPORT void	register_terminate_signal (MoveFunction< void(int)> &&callback, bool is_async=false, bool pass_through=false) noexcept
	Installs a callback for graceful termination signals. More...

VLINK_EXPORT void	register_crash_signal (MoveFunction< void(int)> &&callback) noexcept
	Installs a callback for crash signals such as `SIGSEGV`, `SIGABRT`, `SIGFPE`, `SIGBUS`. More...

VLINK_EXPORT void	start_detect_keyboard (MoveFunction< void(const std::string &key)> &&callback=nullptr, int poll_ms=20) noexcept
	Starts a background poller that detects keyboard input on stdin. More...

VLINK_EXPORT void	stop_detect_keyboard () noexcept
	Stops the keyboard poller started by `start_detect_keyboard()`. More...

VLINK_EXPORT std::pair< int, int >	get_terminal_size () noexcept
	Returns the current terminal dimensions in columns and rows. More...

VLINK_EXPORT double	get_cpu_usage () noexcept
	Returns the system-wide CPU usage as a percentage averaged over all logical CPUs. More...

VLINK_EXPORT double	get_memory_usage () noexcept
	Returns the system-wide memory usage as a percentage of total physical RAM. More...

VLINK_EXPORT bool	is_process_running (const std::string &process_name) noexcept
	Reports whether at least one process with the given executable name is alive. More...

VLINK_EXPORT int32_t	get_timezone_diff () noexcept
	Returns the local timezone offset from UTC in minutes. More...

VLINK_EXPORT std::string	get_machine_id () noexcept
	Returns a stable identifier for the host machine. More...

VLINK_EXPORT void	try_release_sys_memory () noexcept
	Hints to the OS that any unreferenced cached memory pages can be released. More...

Detailed Description

Portable host-system utility functions.

Function Documentation

◆ check_singleton()

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

noexcept

Provides a singleton mutual-exclusion check for a program name.

Uses a Win32 mutex on Windows and a POSIX lock file under VLINK_LOCK_DIR (or the platform default) elsewhere. Returns false when another instance already holds the lock.

Parameters

program_name Program tag used to build the lock identity. Empty defaults to the executable name.

Returns: true when this process holds the singleton lock.

◆ get_all_ipv4_address()

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

noexcept

Returns every IPv4 address bound to a local network interface.

Parameters

filter_available When true, only includes interfaces in the UP state. Default: false.

Returns: Vector of dotted-decimal strings.

◆ get_all_ipv6_address()

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

noexcept

Returns every IPv6 address bound to a local network interface.

Parameters

filter_available When true, only includes interfaces in the UP state. Default: false.

Returns: Vector of IPv6 strings.

◆ get_app_dir()

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

noexcept

Returns the directory portion of the executable's absolute path.

Returns: Directory without a trailing separator, or an empty string on failure.

◆ get_app_name()

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

noexcept

Returns the file-name portion of the executable's absolute path.

Returns: Executable name, or an empty string on failure.

◆ get_app_path()

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

noexcept

Returns the absolute path of the executable that is currently running.

Returns: Full filesystem path, or an empty string when the OS query fails.

◆ get_cpu_usage()

VLINK_EXPORT double vlink::Utils::get_cpu_usage ( )

noexcept

Returns the system-wide CPU usage as a percentage averaged over all logical CPUs.

Implemented as (1 - idle_delta / total_delta) * 100 from /proc/stat on Linux/Android or GetSystemTimes on Windows. Because the previous sample is zero-initialised, the first call after process start reports the average usage since boot rather than the usage over an interval.

Returns: Percentage in [0.0, 100.0], or -1.0 on error / unsupported platform.

◆ get_dds_default_address()

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

noexcept

Selects IPv4 addresses suitable as DDS participant unicast locators.

When 127.0.0.1 is present it is placed first in the result; the remaining non-loopback unicast addresses are then appended until max_count is reached. Loopback is therefore included (as the leading entry) rather than filtered out.

Parameters

filter_available	When `true`, only includes UP interfaces. Default: `false`.
max_count	Upper bound on the number of returned addresses. Default: `5`.

Returns: Vector of selected IPv4 strings.

◆ get_env()

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

noexcept

Reads the current value of an environment variable.

Parameters

key	Variable name.
default_value	Value returned when `key` is not set. Default: empty string.

Returns: Variable value, or default_value when unset.

◆ get_host_name()

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

noexcept

Returns the local machine's host name as reported by the operating system.

Returns: Host name string, or an empty string on failure.

◆ get_interface_name_by_ipv4()

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

noexcept

Returns the interface name that owns a given IPv4 address.

Parameters

ipv4	Address to look up.

Returns: Interface name, or an empty string when no match exists.

◆ get_interface_name_by_ipv6()

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

noexcept

Returns the interface name that owns a given IPv6 address.

Parameters

ipv6	Address to look up.

Returns: Interface name, or an empty string when no match exists.

◆ get_machine_id()

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

noexcept

Returns a stable identifier for the host machine.

Reads /etc/machine-id on Linux and uses platform-specific equivalents elsewhere.

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

◆ get_memory_usage()

VLINK_EXPORT double vlink::Utils::get_memory_usage ( )

noexcept

Returns the system-wide memory usage as a percentage of total physical RAM.

Returns: Percentage in [0.0, 100.0], or -1.0 on error / unsupported platform.

◆ get_native_thread_id()

VLINK_EXPORT uint64_t vlink::Utils::get_native_thread_id ( )

noexcept

Returns the native OS thread identifier of the calling thread.

Maps to:

Linux / Android / QNX: syscall(SYS_gettid) — kernel TID matching top / perf.
macOS / iOS: pthread_threadid_np() — 64-bit Mach thread id.
Windows: GetCurrentThreadId() — Win32 thread id.

Returns: Native thread identifier.

◆ get_pid()

VLINK_EXPORT int32_t vlink::Utils::get_pid ( )

noexcept

Returns the process identifier of the calling process.

Returns: PID, or -1 on failure.

◆ get_pid_str()

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

noexcept

Returns the process identifier of the calling process as a decimal string.

Returns: PID string, or an empty string on failure.

◆ get_terminal_size()

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

noexcept

Returns the current terminal dimensions in columns and rows.

Returns: Pair {columns, rows}; {-1, -1} when stdout is not a TTY.

◆ get_timezone_diff()

VLINK_EXPORT int32_t vlink::Utils::get_timezone_diff ( )

noexcept

Returns the local timezone offset from UTC in minutes.

UTC+8 returns 480; UTC-5 returns -300.

Returns: Offset in minutes.

◆ get_tmp_dir()

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

noexcept

Returns a path suitable for short-lived temporary files.

Honours the VLINK_TMP_DIR environment override. Otherwise falls back to std::filesystem::temp_directory_path(), or /var/log on QNX.

Returns: Temporary directory path.

◆ is_ignored_iface_name()

VLINK_EXPORT bool vlink::Utils::is_ignored_iface_name ( const char * name )

noexcept

Returns whether an interface name is treated as virtual/tunnel-only by address discovery.

Used by get_all_ipv4_address(true) and get_all_ipv6_address(true) to skip container, VPN, bridge and tunnel adapters when choosing transport discovery addresses.

Parameters

name	Interface name; `nullptr` is treated as ignored.

Returns: true when the name should be filtered out.

◆ is_process_running()

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

noexcept

Reports whether at least one process with the given executable name is alive.

Parameters

process_name Executable name without a path component.

Returns: true when a matching process exists.

◆ register_crash_signal()

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

noexcept

Installs a callback for crash signals such as SIGSEGV, SIGABRT, SIGFPE, SIGBUS.

Useful for emitting crash diagnostics. The callback should be async-signal-safe and short.

Parameters

callback Callback receiving the signal number.

◆ register_terminate_signal()

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

noexcept

Installs a callback for graceful termination signals.

Hooks SIGINT, SIGTERM and SIGHUP on POSIX, or SIGINT / SIGTERM on Windows.

Parameters

callback	Callback receiving the signal number.
is_async	When `true`, runs the callback on a dedicated thread instead of the signal context. Default: `false`.
pass_through	When `true`, re-raises the signal after the callback returns so the default OS behaviour also fires. Default: `false`.

◆ set_console_utf8_output()

VLINK_EXPORT void vlink::Utils::set_console_utf8_output ( )

noexcept

Sets the Windows console output code page to UTF-8.

Calls SetConsoleOutputCP(CP_UTF8); a no-op on non-Windows targets.

◆ 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	Variable name.
value	Variable value.
force	When `true` (default), overwrites an existing variable.

Returns: true on success.

◆ set_thread_name()

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

noexcept

Sets the OS-visible name of a thread so debug tools display it.

Parameters

name	Thread name; Linux truncates beyond 15 characters.
thread	Thread to rename, or `nullptr` for the calling thread. Default: `nullptr`.

Returns: true on success.

◆ set_thread_priority()

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

noexcept

Updates the scheduling policy and priority of a thread.

On Linux wraps pthread_setschedparam. Real-time policies require CAP_SYS_NICE or an adequate RLIMIT_RTPRIO. POSIX policy constants (SCHED_FIFO, SCHED_RR, SCHED_OTHER) come from <sched.h>, which callers must include. On Windows the value is mapped to a thread priority class or silently ignored.

Parameters

priority_level	Policy-dependent priority value.
policy	Scheduling policy; `-1` leaves the existing policy untouched.
thread	Thread to configure, or `nullptr` for the calling thread. Default: `nullptr`.

Returns: true on success.

◆ 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 expressed as a bitmask.

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

Parameters

core_mask	Bitmask of CPU cores.
thread	Thread to pin, or `nullptr` for the calling thread. Default: `nullptr`.

Returns: true on success.

◆ start_detect_keyboard()

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

noexcept

Starts a background poller that detects keyboard input on stdin.

Calls callback with a key name string (such as "enter" or "q") whenever a key is detected. Stop with stop_detect_keyboard().

Parameters

callback	Callback receiving the key name. Default: `nullptr` (ignore events).
poll_ms	Polling interval in milliseconds. Default: `20`.

◆ stop_detect_keyboard()

VLINK_EXPORT void vlink::Utils::stop_detect_keyboard ( )

noexcept

Stops the keyboard poller started by start_detect_keyboard().

◆ 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 invokes malloc_trim(0); on other platforms it is a no-op.

◆ unset_env()

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

noexcept

Removes an environment variable.

Parameters

key	Variable name.

Returns: true on success.

◆ wait_for_device()

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

noexcept

Polls a filesystem path until it exists or a timeout expires.

Useful for waiting for device nodes (e.g. /dev/video0) at startup.

Parameters

path	Filesystem path to poll.
timeout_ms	Maximum total wait in milliseconds.
poll_ms	Polling interval in milliseconds. Default: `50`.

Returns: true when the path appears within the timeout.

◆ yield_cpu()

void vlink::Utils::yield_cpu ( )

inlinenoexcept

Emits the most efficient CPU pause/yield hint for the host ISA.

Details.

Maps to PAUSE on x86, YIELD on ARMv7/AArch64, an explicit fence on RISC-V, and std::this_thread::yield() as a portable fallback. Always inlined.

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_ignored_iface_name()

◆ 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()