utils.h File Reference

Platform-agnostic system utilities for process, thread, network and signal management. More...

#include <functional>
#include <string>
#include <thread>
#include <utility>
#include <vector>
#include "./macros.h"

Include dependency graph for utils.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Namespaces
namespace	vlink
namespace	vlink::Utils
	Platform-agnostic system utility functions.

Functions
VLINK_EXPORT std::string	vlink::Utils::get_app_path () noexcept
	Returns the absolute path of the running executable.
VLINK_EXPORT std::string	vlink::Utils::get_app_dir () noexcept
	Returns the directory containing the running executable.
VLINK_EXPORT std::string	vlink::Utils::get_app_name () noexcept
	Returns the file name of the running executable (without directory prefix).
VLINK_EXPORT std::string	vlink::Utils::get_host_name () noexcept
	Returns the host name of the current machine.
VLINK_EXPORT int32_t	vlink::Utils::get_pid () noexcept
	Returns the process ID of the current process.
VLINK_EXPORT std::string	vlink::Utils::get_pid_str () noexcept
	Returns the process ID of the current process as a decimal string.
VLINK_EXPORT std::string	vlink::Utils::get_tmp_dir () noexcept
	Returns the platform-specific temporary directory path.
VLINK_EXPORT std::string	vlink::Utils::get_env (const std::string &key, const std::string &default_value="") noexcept
	Reads the value of an environment variable.
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.
VLINK_EXPORT bool	vlink::Utils::unset_env (const std::string &key) noexcept
	Removes an environment variable.
VLINK_EXPORT std::vector< std::string >	vlink::Utils::get_all_ipv4_address (bool filter_available=false) noexcept
	Returns all IPv4 addresses assigned to local network interfaces.
VLINK_EXPORT std::vector< std::string >	vlink::Utils::get_all_ipv6_address (bool filter_available=false) noexcept
	Returns all IPv6 addresses assigned to local network interfaces.
VLINK_EXPORT std::string	vlink::Utils::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	vlink::Utils::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 >	vlink::Utils::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	vlink::Utils::check_singleton (const std::string &program_name="") noexcept
	Checks that only one instance of the process is running (singleton guard).
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.
VLINK_EXPORT void	vlink::Utils::yield_cpu () noexcept
	Emits a CPU pause/yield hint to reduce bus contention in busy-wait loops.
VLINK_EXPORT void	vlink::Utils::set_console_utf8_output () noexcept
	Configures the Windows console for UTF-8 output.
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).
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.
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.
VLINK_EXPORT uint64_t	vlink::Utils::get_native_thread_id () noexcept
	Returns the native OS thread identifier of the calling thread.
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.).
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.).
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.
VLINK_EXPORT void	vlink::Utils::stop_detect_keyboard () noexcept
	Stops the keyboard detection thread started by start_detect_keyboard().
VLINK_EXPORT std::pair< int, int >	vlink::Utils::get_terminal_size () noexcept
	Returns the current terminal window dimensions.
VLINK_EXPORT double	vlink::Utils::get_cpu_usage () noexcept
	Returns the current CPU usage of the process as a percentage.
VLINK_EXPORT double	vlink::Utils::get_memory_usage () noexcept
	Returns the resident set size (RSS) of the process as a percentage of total RAM.
VLINK_EXPORT bool	vlink::Utils::is_process_running (const std::string &process_name) noexcept
	Checks whether a process with the given name is currently running.
VLINK_EXPORT int32_t	vlink::Utils::get_timezone_diff () noexcept
	Returns the local timezone offset from UTC in seconds.
VLINK_EXPORT std::string	vlink::Utils::get_machine_id () noexcept
	Returns a unique identifier for the current machine.
VLINK_EXPORT void	vlink::Utils::try_release_sys_memory () noexcept
	Hints to the OS that any unreferenced cached memory pages can be released.

Detailed Description

Platform-agnostic system utilities for process, thread, network and signal management.

The Utils namespace provides a set of free functions that wrap platform-specific system calls into a portable API. Supported targets include Linux, macOS, Windows, QNX, and Android.

Note

• All functions are noexcept – errors are indicated by empty strings, false return values or sentinel values (e.g., pid == -1).
• yield_cpu() is inlined and emits the most efficient CPU-pause instruction for the target architecture (PAUSE on x86, YIELD on ARM, .word 0x0100000f on RISC-V).

Example

// Set thread name and pin to cores 0 and 1:
vlink::Utils::set_thread_name("worker");
vlink::Utils::set_thread_stick(0b11);
 
// Register SIGTERM / SIGINT handler:
vlink::Utils::register_terminate_signal([](int sig) {
  // shutdown logic
});