Pulp 1.88.0
Cross-platform audio plugin framework
Loading...
Searching...
No Matches
pulp::runtime Namespace Reference

Namespaces

namespace  detail

Classes

class  ActivityChannel
 A fixed set of lock-free occurrence counters. More...
class  AliveToken
 Shared, fail-closed lifetime signal for callbacks that may outlive an owner. More...
struct  AnalyticsEvent
 Single analytics event. More...
class  AnalyticsDestination
 Abstract destination for analytics events. More...
class  FileAnalyticsDestination
 File-based analytics destination (writes JSON lines). More...
class  Analytics
 Analytics singleton — thread-safe event logging. More...
class  WidgetTracker
 Widget interaction tracker — automatically logs UI events. More...
struct  AsyncStreamOptions
class  AsyncStream
struct  BackgroundJobProgress
class  BackgroundJobContext
class  BackgroundJobHandle
struct  BackgroundJobOptions
class  BackgroundJobService
class  RealtimeResourceSlot
 Control-thread owner for resources prepared off the audio thread and read from the audio thread through an atomic raw pointer. More...
class  BigInteger
 Arbitrary-precision unsigned integer backed by Mbed TLS MPI. More...
struct  RuntimeBudgetPolicy
struct  RuntimeBudgetRequest
struct  RuntimeBudgetDecision
struct  RuntimeBudgetFrameStats
class  RuntimeBudgetFrame
class  CancelRegistration
 RAII registration returned by CancelToken::register_callback. More...
class  CancelToken
class  CancelSource
 Move-only owner of a cancellation state. More...
class  CancellationToken
 Former name of the shared token. More...
struct  GcmOutput
 Output of AES-GCM encryption: ciphertext + 16-byte authentication tag. More...
struct  Ed25519KeyPair
 Ed25519 keypair (NaCl convention: secret key contains seed || public key). More...
struct  X25519KeyPair
 X25519 keypair. More...
class  DynamicLibrary
class  ExpressionEvaluator
 Expression evaluator with persistent variable state. More...
struct  ExternalInputFrame
struct  ExternalInputPolicy
struct  ExternalInputCounters
class  ExternalInputGate
class  FileSearchPath
class  FixedFunction
class  FixedFunction< R(Args...), Capacity, Alignment >
class  HighResolutionTimer
struct  HttpRequest
struct  HttpResponse
class  LocalisedStrings
 Translation string lookup — maps keys to localized strings. More...
struct  Uuid
struct  SessionId
struct  RunId
struct  ObjectId
struct  CorrelationId
struct  EventEnvelope
class  InterProcessLock
struct  JsonRpcError
 Structured JSON-RPC error. Matches spec §5.1. More...
struct  JsonRpcResult
 Result of a request handler: success JSON (result field) or error. More...
class  JsonRpcPeer
struct  LicenseInfo
 Parsed license key data. More...
class  LicenseValidator
 License key validator — checks v1 RSA-signed or v2 AES-256-GCM keys. More...
class  LicenseGenerator
 License key generator (server-side utility). More...
struct  OnlineActivationOptions
 Transport policy for OnlineActivation. More...
struct  OnlineActivation
 Online license activation flow. More...
struct  FileLogSinkOptions
class  FileLogSink
 Appends records to a rotating file. More...
struct  LogRecord
class  CaptureLogSink
 Keeps the most recent records in memory. More...
class  ScopedLogSink
 Installs sink for the lifetime of the object and restores the previous sink after. More...
class  MacAddress
 48-bit MAC address (IEEE 802 EUI-48). More...
struct  FileIdentity
class  AccessPolicyTarget
class  MemoryMappedFile
class  MemoryMessageChannel
struct  Message
 A single structured message as delivered by the channel. More...
class  MessageChannel
 Abstract base for message-oriented channels. More...
struct  DownloadProgress
struct  HttpHeader
struct  DownloadRequest
struct  DownloadResult
struct  ResolvedRedirect
 A redirect Location resolved against the request it answered. More...
struct  ModelAsset
struct  ModelEntry
struct  InstalledModelRecord
struct  ListedModel
struct  ModelListResult
struct  ActivateModelResult
struct  InstallModelResult
class  NamedPipe
class  TcpStream
 Stream backed by a connected TCP Socket. More...
class  HttpStream
 HTTP response as a readable Stream. More...
struct  Range
class  Err
 Wrap a value as a failure result. More...
class  Ok
 Wrap a value as a success result. More...
class  Result
 Result<T, E> — either holds a T or an E, never both. More...
class  Result< void, E >
 Result<void, E> — an operation that either succeeded or failed with E. More...
class  ScopeGuard
class  ScopedNoAlloc
 RAII guard that marks the current thread as "must not allocate". More...
class  ScopedAllocAllowed
 Narrow RAII exemption that SUSPENDS the no-alloc contract on the current thread while alive, even when one or more ScopedNoAlloc guards are still on the stack. More...
struct  SearchQueryOptions
class  SearchIndex
class  SeqLock
 Lock-free reader/writer for reading multi-field structs as consistent snapshots. More...
class  Slot
 Lock-free publication to a reader that must never block. More...
class  Handoff
 Lock-free transfer of ownership to a reader that must never block, plus a ring for handing the displaced value back so the audio thread never frees. More...
struct  LocalPeerCredentials
 Credentials reported by the kernel for the process on the other end of an OS-local stream. More...
class  Socket
struct  SpscQueueTelemetry
class  SpscQueue
class  SpscRingIndex
struct  StreamResult
 Result of a Stream read/write. More...
class  Stream
 Base class for all Pulp byte streams. More...
class  FileStream
 Stream backed by std::FILE* (for portability across Windows/POSIX). More...
class  MemoryStream
 Stream backed by an in-memory byte buffer. More...
class  PipeStream
 Stream wrapper over NamedPipe. More...
struct  SystemInfo
class  TemporaryFile
struct  DiffEntry
struct  TraceStopResult
 Result of stopping a session: the flushed trace path + basic loss accounting so a caller can tell whether the ring dropped data under load (plan §0b #4). More...
class  TraceOwnership
 Opaque authority over one exact process-global trace generation. More...
struct  TraceStartResult
struct  TraceOwnershipStatus
 Atomic view of the process-global session relative to one ownership token. More...
class  Tracing
 Process-global tracing controller. More...
class  ScopedTracingAttachment
 RAII attachment. More...
class  TripleBuffer
 Lock-free triple buffer for publishing the latest value from a writer thread to a reader thread without blocking either side. More...
class  UdevMonitor
struct  Url
 Parsed URL components. More...
class  WakeSignal
 A wake signal from one or more producers (typically the audio thread) to a single consumer thread that sleeps until there is work. More...
struct  WebSocketOptions
 Options for WebSocketChannel construction. More...
class  WebSocketChannel
class  XmlDocument
 Parsed XML document (RAII wrapper over pugi::xml_document). More...

Typedefs

template<std::size_t LaneCount>
using SharedActivityChannel = std::shared_ptr<ActivityChannel<LaneCount>>
using AsyncExecutor = std::function<void(std::function<void()>)>
 Executor hook: a function that schedules work on some thread.
using AsyncWriteCallback = std::function<void(std::size_t bytes, StreamError error)>
 Completion callback for write_async.
using AsyncDataCallback = std::function<void(const std::uint8_t* data, std::size_t size)>
 Incoming-data callback.
using AsyncErrorCallback = std::function<void(StreamError error)>
 Error callback.
using AsyncCloseCallback = std::function<void()>
 Close callback.
using BackgroundJobFunction = std::function<void(BackgroundJobContext&)>
using CancelCallback = std::function<void()>
 Callback run when a token is cancelled.
using ProcessResult = pulp::platform::ProcessResult
using ExternalInputScalar = ExternalInputFrame<1>
using HttpHeaders = std::map<std::string, std::string>
using HttpChunkCallback = std::function<bool(std::string_view)>
using JsonRpcMethodHandler
 Request handler: given a JSON-encoded params string (empty if omitted), return a JsonRpcResult.
using JsonRpcNotificationHandler
 Notification handler (incoming notifications carry no id and expect no response).
using JsonRpcResponseCallback
 Callback for the response to a request we sent.
using LogSink
 Receives every record after the platform writers.
using MessageCallback = std::function<void(const Message& message)>
 Called when the channel receives a complete message.
using ChannelClosedCallback = std::function<void()>
 Called once when the channel transitions to a closed state — either the peer closed, the transport errored, or close() was invoked.
using ChannelErrorCallback = std::function<void(std::string_view reason)>
 Called when a transport-level error occurs.
using MessageExecutor = std::function<void(std::function<void()>)>
 Executor used to dispatch callbacks off whichever worker thread the channel runs internally.
using DownloadProgressFn = std::function<bool(const DownloadProgress&)>
 Progress callback. Return false to cancel the in-flight download.
using IntRange = Range<int>
using FloatRange = Range<float>
using DoubleRange = Range<double>
using SizeRange = Range<size_t>

Enumerations

enum class  BackgroundJobPriority { low = 0 , normal = 1 , high = 2 }
enum class  RealtimeResourceSlotPublishStatus : std::uint8_t { Published , RejectedEmptyResource , RejectedRetireQueueFull }
enum class  RuntimeWorkLane : std::uint8_t { CriticalAudio = 0 , Interactive , Background , Opportunistic }
enum class  RuntimeBudgetAction : std::uint8_t { Run = 0 , Defer , Shed , Bypass }
enum class  ExternalInputStatus : std::uint8_t {
  valid , invalid , unavailable , denied ,
  paused
}
enum class  ExternalInputVerdict : std::uint8_t {
  accepted , unchanged , rejected_status , rejected_source ,
  rejected_order , rejected_malformed , rejected_confidence
}
enum class  TimerMode { DedicatedThread , OsTimerQueue }
 Backend selection for the high-resolution timer. More...
enum class  LicenseFormatVersion { V1 = 1 , V2 = 2 }
 License-key format version. More...
enum class  LicenseStatus {
  Valid , Expired , InvalidSignature , InvalidFormat ,
  MachineIdMismatch , NotFound
}
 License key status. More...
enum class  LogLevel { Debug , Info , Warning , Error }
enum class  MapMode { ReadOnly , ReadWrite }
enum class  MessageKind : uint8_t { Binary , Text }
 Classification of a delivered message. More...
enum class  SocketType { TCP , UDP , Local }
enum class  StreamError : uint8_t {
  Ok , Closed , WouldBlock , IoError ,
  Invalid
}
 High-level error classification for Stream operations. More...
enum class  DiffOp { Equal , Insert , Delete }
enum class  TraceStartStatus { Started , AlreadyActive , Unavailable }
 Outcome of an exclusive attempt to start the process-global trace session. More...
enum class  UdevChange { added , removed , other }
 Classification of a udev action string. Pure + testable on every platform. More...

Functions

template<std::size_t LaneCount>
SharedActivityChannel< LaneCount > make_activity_channel ()
void assert_fail (std::string_view expr, std::string_view msg, std::source_location loc=std::source_location::current())
constexpr bool realtime_resource_slot_publish_succeeded (RealtimeResourceSlotPublishStatus status) noexcept
std::string base64_encode (const uint8_t *data, size_t length)
 Encode binary data to base64 string.
std::string base64_encode (std::string_view input)
std::optional< std::vector< uint8_t > > base64_decode (std::string_view input)
 Decode base64 string to binary data. Returns nullopt on invalid input.
const char * to_string (RuntimeBudgetAction action) noexcept
RuntimeBudgetDecision evaluate_runtime_budget (const RuntimeBudgetRequest &request, const RuntimeBudgetPolicy &policy={}) noexcept
std::optional< ProcessResult > run_process (std::string_view executable, const std::vector< std::string > &args={}, std::string_view working_dir="", int timeout_ms=0)
 Launch a child process and wait for it to complete.
std::optional< std::vector< uint8_t > > secure_random_bytes (size_t size)
 Generate bytes from the runtime's entropy-seeded CTR-DRBG.
void secure_zero_memory (void *data, size_t size) noexcept
 Overwrite sensitive bytes through volatile stores so the wipe is not removed as a dead store when the containing object is destroyed.
std::string hex_encode (const uint8_t *data, size_t size)
 Lowercase-hex encode raw bytes.
std::string hex_encode (const std::vector< uint8_t > &bytes)
std::vector< uint8_t > sha256 (const uint8_t *data, size_t size)
 Compute SHA-256 hash.
std::vector< uint8_t > sha256 (std::string_view data)
std::string sha256_hex (const uint8_t *data, size_t size)
 Compute SHA-256 hash as hex string (64 chars).
std::string sha256_hex (std::string_view data)
std::optional< std::string > sha256_file_hex (const std::filesystem::path &path, std::uint64_t max_bytes)
 Stream a file through SHA-256 without retaining its contents in memory.
std::vector< uint8_t > sha1 (const uint8_t *data, size_t size)
 Compute SHA-1 hash.
std::vector< uint8_t > sha1 (std::string_view data)
std::vector< uint8_t > md5 (const uint8_t *data, size_t size)
 Compute MD5 hash. Returns 16-byte digest. (Legacy use only.).
std::vector< uint8_t > md5 (std::string_view data)
std::string md5_hex (std::string_view data)
 Compute MD5 hash as hex string (32 chars).
std::optional< std::vector< uint8_t > > aes_encrypt (const uint8_t *plaintext, size_t size, const uint8_t *key_32, const uint8_t *iv_16)
 AES-256-CBC encrypt.
std::optional< std::vector< uint8_t > > aes_decrypt (const uint8_t *ciphertext, size_t size, const uint8_t *key_32, const uint8_t *iv_16)
 AES-256-CBC decrypt. Returns plaintext (PKCS7 unpadded).
std::optional< std::vector< uint8_t > > hmac_sha256 (const uint8_t *key, size_t key_size, const uint8_t *data, size_t data_size)
 Compute HMAC-SHA256(key, data).
std::optional< std::vector< uint8_t > > hmac_sha256 (std::string_view key, std::string_view data)
std::optional< std::vector< uint8_t > > hmac_sha1 (const uint8_t *key, size_t key_size, const uint8_t *data, size_t data_size)
 Compute HMAC-SHA1(key, data).
std::optional< GcmOutput > aes_gcm_encrypt (const uint8_t *plaintext, size_t plaintext_size, const uint8_t *key_32, const uint8_t *iv_12, size_t iv_size, const uint8_t *aad, size_t aad_size)
 AES-256-GCM encrypt with optional Additional Authenticated Data (AAD).
std::optional< std::vector< uint8_t > > aes_gcm_decrypt (const uint8_t *ciphertext, size_t ciphertext_size, const uint8_t *key_32, const uint8_t *iv_12, size_t iv_size, const uint8_t *aad, size_t aad_size, const uint8_t *tag_16)
 AES-256-GCM decrypt + verify the 16-byte tag.
bool constant_time_equal (const uint8_t *a, const uint8_t *b, size_t size)
 Constant-time byte comparison.
std::optional< Ed25519KeyPair > ed25519_keypair_generate ()
 Generate a fresh Ed25519 keypair using mbedTLS CTR-DRBG for entropy.
std::optional< Ed25519KeyPair > ed25519_keypair_from_seed (const uint8_t *seed_32, size_t seed_size)
 Derive a deterministic Ed25519 keypair from a 32-byte seed.
std::optional< std::vector< uint8_t > > ed25519_sign (const uint8_t *private_key_64, size_t private_key_size, const uint8_t *message, size_t message_size)
 Sign a message with an Ed25519 private key (64-byte NaCl-form).
bool ed25519_verify (const uint8_t *public_key_32, size_t public_key_size, const uint8_t *signature_64, size_t signature_size, const uint8_t *message, size_t message_size)
 Verify a 64-byte detached signature against a message + 32-byte public key.
std::optional< X25519KeyPair > x25519_keypair_generate ()
 Generate a fresh X25519 keypair using mbedTLS CTR-DRBG for entropy.
std::optional< X25519KeyPair > x25519_keypair_from_private_key (const uint8_t *private_key_32, size_t private_key_size)
 Recover the public key for an existing 32-byte private scalar.
std::optional< std::vector< uint8_t > > x25519_shared_secret (const uint8_t *private_key_32, size_t private_key_size, const uint8_t *peer_public_key_32, size_t peer_public_key_size)
 Compute the raw X25519 shared secret between our private key and a peer's public key.
std::string machine_id ()
 Generate a machine-specific fingerprint (deterministic per machine).
template<std::size_t Max, typename Fn>
constexpr bool dispatch_count (std::size_t n, Fn &&fn)
 Call fn(std::integral_constant<std::size_t, n>{}) for a run-time n in [1, Max], so a kernel can be instantiated per count (fixed-size local arrays, fully unrolled inner loops) and selected at run time without a hand-written switch.
std::optional< double > evaluate (std::string_view expression, const std::map< std::string, double > &variables={})
 Evaluate a math expression string.
HttpResponse http_request (const HttpRequest &request)
 Perform an HTTP request. GET and POST are supported.
HttpResponse http_get (std::string_view url, int timeout_seconds=30)
 Perform an HTTP GET request.
HttpResponse http_post (std::string_view url, std::string_view body, std::string_view content_type="application/json", int timeout_seconds=30)
 Perform an HTTP POST request with a body.
bool http_download (std::string_view url, std::string_view output_path, int timeout_seconds=60)
 Download a file from a URL to a local path. Returns true on success.
std::string tr (std::string_view key)
 Convenience: translate a key using the global instance.
std::string tr (std::string_view key, const std::vector< std::string > &args)
 Convenience: translate with arguments.
bool is_valid_ipv4 (std::string_view address)
 Parse and validate an IPv4 address.
std::vector< std::string > local_ipv4_addresses ()
 Get all local IPv4 addresses (excluding loopback).
std::string local_ipv4_address ()
 Get the primary local IPv4 address (first non-loopback).
std::string hostname ()
 Get the hostname.
std::optional< LicenseFormatVersion > detect_license_format (std::string_view license_key)
 Detect the format version of a license key without parsing the payload.
std::optional< std::string > migrate_v1_to_v2 (std::string_view v1_license_key, std::string_view v1_public_key_pem, const uint8_t *v2_secret_32, size_t v2_secret_size)
 Re-encode a v1 license key as v2 using the supplied 32-byte secret.
LogSink set_log_sink (LogSink sink)
 Install sink as the process-wide log sink and return the previous one (empty if none).
template<typename... Args>
void log_with_category (std::string_view category, LogLevel level, std::format_string< Args... > fmt, Args &&... args)
 Log with an explicit category (a subsystem tag such as "audio" or "net").
template<typename... Args>
void log (LogLevel level, std::format_string< Args... > fmt, Args &&... args)
template<typename... Args>
void log_debug (std::format_string< Args... > fmt, Args &&... args)
template<typename... Args>
void log_info (std::format_string< Args... > fmt, Args &&... args)
template<typename... Args>
void log_warn (std::format_string< Args... > fmt, Args &&... args)
template<typename... Args>
void log_error (std::format_string< Args... > fmt, Args &&... args)
FileIdentity file_identity (std::string_view path) noexcept
int download_connect_timeout_seconds (int request_timeout_seconds)
 Connect-phase timeout (seconds) the downloader applies for a given request timeout_seconds.
ResolvedRedirect resolve_redirect (const std::string &current_scheme_host_port, const std::string &current_path, const std::string &location)
 Resolve an absolute, host-absolute, or path-relative redirect location against the current origin + path.
DownloadResult download_file (const DownloadRequest &request, const DownloadProgressFn &on_progress={}, const CancelToken *cancel=nullptr)
 Blocking streaming download.
std::string resolve_checkpoint_url (const std::string &checkpoint_ref)
 Resolve a checkpoint_ref to a direct download URL.
const ModelEntry * find_model (const std::vector< ModelEntry > &registry, std::string_view model_id)
 Find a model by id in a caller-supplied registry/catalog. Returns nullptr if absent.
std::filesystem::path resolve_pulp_home (const std::filesystem::path &override_path={})
std::filesystem::path model_state_path (std::string_view subsystem, const std::filesystem::path &pulp_home_override={})
std::filesystem::path model_install_path (std::string_view subsystem, std::string_view model_id, const std::filesystem::path &pulp_home_override={})
InstalledModelRecord read_installed_model (std::string_view subsystem, std::string_view model_id, const std::filesystem::path &pulp_home_override={})
std::string read_active_model_id (std::string_view subsystem, const std::filesystem::path &pulp_home_override={})
ModelListResult list_models (const std::vector< ModelEntry > &registry, std::string_view subsystem, const std::filesystem::path &pulp_home_override={})
ActivateModelResult activate_model (const std::vector< ModelEntry > &registry, std::string_view subsystem, std::string_view model_id, const std::filesystem::path &pulp_home_override={})
std::string to_json (const ModelListResult &result)
std::string to_json (const ActivateModelResult &result)
InstallModelResult install_model (const ModelEntry &model, std::string_view subsystem, const std::function< bool(const struct DownloadProgress &)> &on_progress={}, const CancelToken *cancel=nullptr, const std::vector< std::pair< std::string, std::string > > &headers={}, const std::filesystem::path &pulp_home_override={}, bool allow_unverified=false)
 Download model's checkpoint into <home>/<subsystem>/models/<id>/ (streaming, resumable, sha256-verified), then write the install metadata so read_installed_model/ activate_model see it.
bool remove_model (std::string_view subsystem, std::string_view model_id, std::string &error, const std::filesystem::path &pulp_home_override={})
 Delete an installed model's files + metadata.
bool is_prime (uint64_t n, int rounds=40)
 Test if a number is probably prime (Miller-Rabin).
uint64_t generate_prime (int bits=32)
 Generate a random prime of the given bit length.
std::vector< uint32_t > sieve_primes (uint32_t limit)
 Generate the first N primes via sieve of Eratosthenes.
template<typename T>
 Ok (T) -> Ok< T >
template<typename E>
 Err (E) -> Err< E >
bool is_safe_relative_path (const std::filesystem::path &path)
 True only if path is safe to join beneath a destination directory: a non-empty relative path with no root name (C:, \\server), no root directory (/ or \\endiskip), and no component that is empty, .
bool is_within_directory (const std::filesystem::path &directory, const std::filesystem::path &candidate)
 True if candidate, compared lexically after normalization, is directory itself or lies beneath it.
template<typename F>
ScopeGuard< F > make_scope_guard (F &&fn)
bool is_in_no_alloc_scope () noexcept
int no_alloc_scope_depth () noexcept
 Depth of nested ScopedNoAlloc instances on the current thread.
int no_alloc_allowed_depth () noexcept
 Depth of nested ScopedAllocAllowed instances on the current thread.
std::size_t simd_float_lanes ()
std::size_t simd_double_lanes ()
void simd_add (const float *a, const float *b, float *dst, std::size_t count)
void simd_add (const double *a, const double *b, double *dst, std::size_t count)
void simd_mul (const float *a, const float *b, float *dst, std::size_t count)
void simd_mul (const double *a, const double *b, double *dst, std::size_t count)
void simd_fma (const float *a, const float *b, const float *c, float *dst, std::size_t count)
void simd_fma (const double *a, const double *b, const double *c, double *dst, std::size_t count)
void simd_set (float value, float *dst, std::size_t count)
void simd_set (double value, double *dst, std::size_t count)
void simd_scale (const float *a, float scalar, float *dst, std::size_t count)
void simd_scale (const double *a, double scalar, double *dst, std::size_t count)
void simd_add_scaled (const float *a, float scalar, float *dst, std::size_t count)
void simd_add_scaled (const double *a, double scalar, double *dst, std::size_t count)
float simd_reduce_add (const float *data, std::size_t count)
double simd_reduce_add (const double *data, std::size_t count)
float simd_reduce_max (const float *data, std::size_t count)
double simd_reduce_max (const double *data, std::size_t count)
float simd_reduce_min (const float *data, std::size_t count)
double simd_reduce_min (const double *data, std::size_t count)
void simd_abs (const float *a, float *dst, std::size_t count)
void simd_abs (const double *a, double *dst, std::size_t count)
void simd_clamp (const float *a, float lo, float hi, float *dst, std::size_t count)
void simd_clamp (const double *a, double lo, double hi, double *dst, std::size_t count)
std::optional< std::string > get_env (std::string_view name)
std::tm gmtime_utc (std::time_t value)
std::tm localtime_local (std::time_t value)
void copy_c_string (char *dest, std::size_t dest_size, std::string_view src)
template<std::size_t N>
void copy_c_string (char(&dest)[N], std::string_view src)
const SystemInfo & get_system_info ()
 Query system information (cached after first call).
int cpu_thread_count ()
 Number of logical CPU threads (convenience).
uint64_t total_memory_mb ()
 Total physical memory in MB (convenience).
std::vector< DiffEntry > text_diff (std::string_view from, std::string_view to)
 Compute a line-based diff between two strings.
std::string format_diff (const std::vector< DiffEntry > &diff)
 Format a diff as a unified diff string (with +/- prefixes).
bool tracing_reminder_first_time (std::atomic< bool > &already_emitted)
 One-shot gate for the "tracing compiled in" reminder.
void log_tracing_reminder ()
 Emit — at most once for the whole process — a single dev-build reminder that Perfetto tracing is compiled in.
UdevChange classify_udev_action (const char *action) noexcept
 Map a udev ACTION string to a change kind.
std::string percent_encode (std::string_view s)
 Percent-encode s per RFC 3986 — unreserved characters (A-Z a-z 0-9 - _ .
std::string percent_decode (std::string_view s)
 Decode percent-escapes — %20 → space, %2F → /.
std::string form_encode (std::string_view s)
 application/x-www-form-urlencoded style — space → +, then percent-encode everything else.
std::string form_decode (std::string_view s)
 Reverse of form_encode. + decodes to space.
std::vector< std::pair< std::string, std::string > > parse_query (std::string_view query)
 Parse a URL query string into key/value pairs.
std::string build_query (const std::vector< std::pair< std::string, std::string > > &params)
 Build a query string from key/value pairs.
std::string xml_generate (std::string_view root_name, const std::vector< std::pair< std::string, std::string > > &elements)
 Generate a simple XML string from key-value pairs.
std::optional< std::vector< uint8_t > > gzip_compress (const uint8_t *data, size_t size, int level=6)
 Compress data into an RFC 1952 gzip stream.
std::optional< std::vector< uint8_t > > gzip_decompress (const uint8_t *data, size_t size, size_t max_output=kDefaultMaxDecompressOutput)
 Decompress a gzip (RFC 1952) or zlib (RFC 1950) stream.
std::optional< std::vector< uint8_t > > gzip_compress (std::string_view data, int level=6)
 Convenience: compress a string into an RFC 1952 gzip stream.
std::optional< std::string > gzip_decompress_string (const uint8_t *data, size_t size)
 Convenience: decompress a gzip (RFC 1952) or zlib (RFC 1950) stream into a string.
std::optional< std::vector< uint8_t > > deflate_compress (const uint8_t *data, size_t size, int level=6)
 Compress data using raw deflate (no header).
std::optional< std::vector< uint8_t > > deflate_decompress (const uint8_t *data, size_t size)
 Decompress raw deflate data.
std::optional< std::vector< uint8_t > > zlib_compress (const uint8_t *data, size_t size, int level=6)
 Compress data into an RFC 1950 zlib stream.
std::optional< std::vector< uint8_t > > zlib_decompress (const uint8_t *data, size_t size, size_t max_output=kDefaultMaxDecompressOutput)
 Decompress exactly one RFC 1950 zlib stream.
std::optional< std::string > zlib_decompress_exact (const uint8_t *data, size_t size, size_t expected_size)
 Decompress one RFC 1950 zlib stream whose inflated size is known in advance (an embedded asset that recorded it at build time) straight into a string of exactly that size, with no growth or second copy.

Variables

constexpr size_t ed25519_public_key_size = 32
 Ed25519 key sizes (RFC 8032 §5.1).
constexpr size_t ed25519_private_key_size = 64
constexpr size_t ed25519_seed_size = 32
constexpr size_t ed25519_signature_size = 64
constexpr size_t x25519_public_key_size = 32
 X25519 key and output sizes (RFC 7748 §5).
constexpr size_t x25519_private_key_size = 32
constexpr size_t x25519_shared_secret_size = 32
constexpr LicenseFormatVersion kCurrentLicenseFormat
 Latest format emitted by LicenseGenerator.
constexpr std::string_view kDefaultLogCategory = "pulp"
 Category used by log_info and the other level helpers.
constexpr bool kTracingEnabled = false
 True only in a PULP_TRACING=ON build. Every shipping/default build is false.
constexpr size_t kDefaultMaxDecompressOutput = 256u * 1024u * 1024u
 Default ceiling on total decompressed output (bytes).

Typedef Documentation

◆ AsyncCloseCallback

using pulp::runtime::AsyncCloseCallback = std::function<void()>

Close callback.

Fired once when the stream is no longer usable — either because the underlying Stream closed, because cancel() was invoked, or because the AsyncStream is being destroyed.

◆ AsyncDataCallback

using pulp::runtime::AsyncDataCallback = std::function<void(const std::uint8_t* data, std::size_t size)>

Incoming-data callback.

Called whenever the worker reads bytes from the underlying Stream. data is valid only for the duration of the call.

◆ AsyncErrorCallback

using pulp::runtime::AsyncErrorCallback = std::function<void(StreamError error)>

Error callback.

Fired once per async operation when an error terminates the stream or a write. Cancelled is reported via the dedicated close callback instead.

◆ AsyncExecutor

using pulp::runtime::AsyncExecutor = std::function<void(std::function<void()>)>

Executor hook: a function that schedules work on some thread.

Callers pass a wrapper around their own event loop's dispatch — for example [loop](auto fn) { loop->dispatch(std::move(fn)); }. When null, the AsyncStream runs callbacks on its worker thread.

◆ AsyncWriteCallback

using pulp::runtime::AsyncWriteCallback = std::function<void(std::size_t bytes, StreamError error)>

Completion callback for write_async.

Receives the number of bytes written and an error code; error == Ok means the full payload succeeded (partial writes retry internally until the Stream reports a non-Ok error).

◆ BackgroundJobFunction

◆ CancelCallback

using pulp::runtime::CancelCallback = std::function<void()>

Callback run when a token is cancelled.

It runs on the thread that calls CancelSource::cancel(), or inline on the registering thread when the token is already cancelled. It must not throw; an escaping exception is swallowed.

◆ ChannelClosedCallback

using pulp::runtime::ChannelClosedCallback = std::function<void()>

Called once when the channel transitions to a closed state — either the peer closed, the transport errored, or close() was invoked.

◆ ChannelErrorCallback

using pulp::runtime::ChannelErrorCallback = std::function<void(std::string_view reason)>

Called when a transport-level error occurs.

After an error callback fires, the channel is no longer usable and a close callback will follow.

◆ DoubleRange

◆ DownloadProgressFn

using pulp::runtime::DownloadProgressFn = std::function<bool(const DownloadProgress&)>

Progress callback. Return false to cancel the in-flight download.

◆ ExternalInputScalar

◆ FloatRange

◆ HttpChunkCallback

using pulp::runtime::HttpChunkCallback = std::function<bool(std::string_view)>

◆ HttpHeaders

using pulp::runtime::HttpHeaders = std::map<std::string, std::string>

◆ IntRange

◆ JsonRpcMethodHandler

Initial value:
std::function<JsonRpcResult(std::string_view params_json)>
Result of a request handler: success JSON (result field) or error.
Definition json_rpc.hpp:49

Request handler: given a JSON-encoded params string (empty if omitted), return a JsonRpcResult.

Runs on whichever thread the underlying channel dispatches on.

◆ JsonRpcNotificationHandler

Initial value:
std::function<void(std::string_view params_json)>

Notification handler (incoming notifications carry no id and expect no response).

◆ JsonRpcResponseCallback

Initial value:
std::function<void(const JsonRpcResult& response)>

Callback for the response to a request we sent.

◆ LogSink

Initial value:
std::function<void(LogLevel level, std::string_view category, std::string_view message)>
LogLevel
Definition log.hpp:42

Receives every record after the platform writers.

Invoked on the logging thread, possibly from several threads at once, so it must synchronize its own state. It must not throw (a thrown exception is swallowed) and must not assume it is realtime-safe or that it is the only consumer. Records logged from inside a sink on the same thread are not re-delivered to it.

◆ MessageCallback

using pulp::runtime::MessageCallback = std::function<void(const Message& message)>

Called when the channel receives a complete message.

◆ MessageExecutor

using pulp::runtime::MessageExecutor = std::function<void(std::function<void()>)>

Executor used to dispatch callbacks off whichever worker thread the channel runs internally.

Same shape as AsyncExecutor.

◆ ProcessResult

◆ SharedActivityChannel

template<std::size_t LaneCount>
using pulp::runtime::SharedActivityChannel = std::shared_ptr<ActivityChannel<LaneCount>>

◆ SizeRange

Enumeration Type Documentation

◆ BackgroundJobPriority

Enumerator
low 
normal 
high 

◆ DiffOp

enum class pulp::runtime::DiffOp
strong
Enumerator
Equal 
Insert 
Delete 

◆ ExternalInputStatus

enum class pulp::runtime::ExternalInputStatus : std::uint8_t
strong
Enumerator
valid 
invalid 
unavailable 
denied 
paused 

◆ ExternalInputVerdict

enum class pulp::runtime::ExternalInputVerdict : std::uint8_t
strong
Enumerator
accepted 
unchanged 
rejected_status 
rejected_source 
rejected_order 
rejected_malformed 
rejected_confidence 

◆ LicenseFormatVersion

License-key format version.

v1 is the legacy RSA-signed format; v2 is the AES-256-GCM AEAD format introduced for the macOS 1.0 release.

Enumerator
V1 

base64(json).base64(RSA_sig) — legacy

V2 

"v2." + base64url(IV || AES-256-GCM(json) || tag)

◆ LicenseStatus

enum class pulp::runtime::LicenseStatus
strong

License key status.

Enumerator
Valid 
Expired 
InvalidSignature 
InvalidFormat 
MachineIdMismatch 
NotFound 

◆ LogLevel

enum class pulp::runtime::LogLevel
strong
Enumerator
Debug 
Info 
Warning 
Error 

◆ MapMode

enum class pulp::runtime::MapMode
strong
Enumerator
ReadOnly 
ReadWrite 

◆ MessageKind

enum class pulp::runtime::MessageKind : uint8_t
strong

Classification of a delivered message.

Transports that do not distinguish (OSC, JSON-RPC) report Binary.

Enumerator
Binary 

opaque bytes

Text 

UTF-8 text (WebSocket text frames, JSON-RPC envelopes).

◆ RealtimeResourceSlotPublishStatus

enum class pulp::runtime::RealtimeResourceSlotPublishStatus : std::uint8_t
strong
Enumerator
Published 
RejectedEmptyResource 
RejectedRetireQueueFull 

◆ RuntimeBudgetAction

enum class pulp::runtime::RuntimeBudgetAction : std::uint8_t
strong
Enumerator
Run 
Defer 
Shed 
Bypass 

◆ RuntimeWorkLane

enum class pulp::runtime::RuntimeWorkLane : std::uint8_t
strong
Enumerator
CriticalAudio 
Interactive 
Background 
Opportunistic 

◆ SocketType

enum class pulp::runtime::SocketType
strong
Enumerator
TCP 
UDP 
Local 

◆ StreamError

enum class pulp::runtime::StreamError : uint8_t
strong

High-level error classification for Stream operations.

Enumerator
Ok 

No error; bytes is authoritative.

Closed 

End-of-stream / peer closed / stream not open.

WouldBlock 

No data available now; try again later.

IoError 

OS-level I/O failure (errno/GetLastError set by the backend).

Invalid 

Invalid argument or invalid state (e.g., read after close).

◆ TimerMode

enum class pulp::runtime::TimerMode
strong

Backend selection for the high-resolution timer.

  • DedicatedThread (default): a Pulp-owned worker thread spins or sleeps to the next deadline. Cross-platform; ~1 ms jitter under load. Use when no OS timer queue is available or when the workload runs outside an event loop.
  • OsTimerQueue: backed by the platform's native high-resolution timer queue (macOS / iOS: dispatch_source_create on a leeway-0 timer). No Pulp-owned thread; callbacks fire on the dispatch queue. Lower jitter on supported platforms. Falls back to DedicatedThread on platforms without an equivalent surface (Linux desktop) so the contract holds.
Enumerator
DedicatedThread 
OsTimerQueue 

◆ TraceStartStatus

Outcome of an exclusive attempt to start the process-global trace session.

Inspector control uses this to distinguish a newly configured capture from a session that was already active under another owner.

Enumerator
Started 
AlreadyActive 
Unavailable 

◆ UdevChange

enum class pulp::runtime::UdevChange
strong

Classification of a udev action string. Pure + testable on every platform.

Enumerator
added 
removed 
other 

Function Documentation

◆ activate_model()

ActivateModelResult pulp::runtime::activate_model ( const std::vector< ModelEntry > & registry,
std::string_view subsystem,
std::string_view model_id,
const std::filesystem::path & pulp_home_override = {} )

◆ aes_decrypt()

std::optional< std::vector< uint8_t > > pulp::runtime::aes_decrypt ( const uint8_t * ciphertext,
size_t size,
const uint8_t * key_32,
const uint8_t * iv_16 )

AES-256-CBC decrypt. Returns plaintext (PKCS7 unpadded).

◆ aes_encrypt()

std::optional< std::vector< uint8_t > > pulp::runtime::aes_encrypt ( const uint8_t * plaintext,
size_t size,
const uint8_t * key_32,
const uint8_t * iv_16 )

AES-256-CBC encrypt.

Key must be 32 bytes, IV 16 bytes. Returns ciphertext (PKCS7 padded).

◆ aes_gcm_decrypt()

std::optional< std::vector< uint8_t > > pulp::runtime::aes_gcm_decrypt ( const uint8_t * ciphertext,
size_t ciphertext_size,
const uint8_t * key_32,
const uint8_t * iv_12,
size_t iv_size,
const uint8_t * aad,
size_t aad_size,
const uint8_t * tag_16 )

AES-256-GCM decrypt + verify the 16-byte tag.

Returns plaintext on success; std::nullopt if the tag fails to verify (caller must treat that as a hard failure — do not surface partial plaintext on tag mismatch; the buffer is overwritten regardless but the contract is "verified or null").

◆ aes_gcm_encrypt()

std::optional< GcmOutput > pulp::runtime::aes_gcm_encrypt ( const uint8_t * plaintext,
size_t plaintext_size,
const uint8_t * key_32,
const uint8_t * iv_12,
size_t iv_size,
const uint8_t * aad,
size_t aad_size )

AES-256-GCM encrypt with optional Additional Authenticated Data (AAD).

IV/nonce should be 12 bytes (96 bits) per NIST SP 800-38D §8.2.1. Returns ciphertext (same length as plaintext) + 16-byte authentication tag. Returns std::nullopt on internal mbedTLS failure (rare; mostly OOM).

◆ assert_fail()

void pulp::runtime::assert_fail ( std::string_view expr,
std::string_view msg,
std::source_location loc = std::source_location::current() )
inline

◆ base64_decode()

std::optional< std::vector< uint8_t > > pulp::runtime::base64_decode ( std::string_view input)

Decode base64 string to binary data. Returns nullopt on invalid input.

◆ base64_encode() [1/2]

std::string pulp::runtime::base64_encode ( const uint8_t * data,
size_t length )

Encode binary data to base64 string.

◆ base64_encode() [2/2]

std::string pulp::runtime::base64_encode ( std::string_view input)

◆ build_query()

std::string pulp::runtime::build_query ( const std::vector< std::pair< std::string, std::string > > & params)

Build a query string from key/value pairs.

Applies form_encode to each key and value. Does NOT emit a leading ?.

◆ classify_udev_action()

UdevChange pulp::runtime::classify_udev_action ( const char * action)
noexcept

Map a udev ACTION string to a change kind.

nullptr/unknown → other. "add" → added, "remove" → removed, "bind"/"change"/"unbind"/etc → other.

◆ constant_time_equal()

bool pulp::runtime::constant_time_equal ( const uint8_t * a,
const uint8_t * b,
size_t size )

Constant-time byte comparison.

Returns true iff a and b match. Use whenever comparing MAC tags, key material, or other secret bytes — std::memcmp short-circuits and leaks timing information.

◆ copy_c_string() [1/2]

void pulp::runtime::copy_c_string ( char * dest,
std::size_t dest_size,
std::string_view src )
inline

◆ copy_c_string() [2/2]

template<std::size_t N>
void pulp::runtime::copy_c_string ( char(&) dest[N],
std::string_view src )
inline

◆ cpu_thread_count()

int pulp::runtime::cpu_thread_count ( )

Number of logical CPU threads (convenience).

◆ deflate_compress()

std::optional< std::vector< uint8_t > > pulp::runtime::deflate_compress ( const uint8_t * data,
size_t size,
int level = 6 )

Compress data using raw deflate (no header).

◆ deflate_decompress()

std::optional< std::vector< uint8_t > > pulp::runtime::deflate_decompress ( const uint8_t * data,
size_t size )

Decompress raw deflate data.

◆ detect_license_format()

std::optional< LicenseFormatVersion > pulp::runtime::detect_license_format ( std::string_view license_key)

Detect the format version of a license key without parsing the payload.

Returns std::nullopt if the string matches no known format.

◆ dispatch_count()

template<std::size_t Max, typename Fn>
bool pulp::runtime::dispatch_count ( std::size_t n,
Fn && fn )
constexpr

Call fn(std::integral_constant<std::size_t, n>{}) for a run-time n in [1, Max], so a kernel can be instantiated per count (fixed-size local arrays, fully unrolled inner loops) and selected at run time without a hand-written switch.

Returns false, without calling fn, when n is 0 or above Max.

pulp::runtime::dispatch_count<16>(sections, [&](auto count) {
run_pass<decltype(count)::value>(state, buffer, frames);
});
constexpr bool dispatch_count(std::size_t n, Fn &&fn)
Call fn(std::integral_constant<std::size_t, n>{}) for a run-time n in [1, Max], so a kernel can be in...
Definition dispatch_count.hpp:26
SequencerStateChannel is the audio-safe transport for a plugin's structured NON-parameter state: the ...
Definition audio_device_manager.hpp:48

RT contract: no allocation, no locks; the selection is a chain of integer compares that compilers lower to a jump table.

◆ download_connect_timeout_seconds()

int pulp::runtime::download_connect_timeout_seconds ( int request_timeout_seconds)
inline

Connect-phase timeout (seconds) the downloader applies for a given request timeout_seconds.

Always bounded (never 0), so an unreachable or blocked endpoint fails fast instead of hanging on the HTTP library's multi-minute connection-timeout default — the failure mode seen when a plug-in host sandboxes the audio-unit process's network (download appears stuck at 0% with an unresponsive Cancel, because the cancel/progress callback only runs once body streaming begins). The read/stream phase stays governed by timeout_seconds (0 ⇒ library default) so large bodies aren't capped here.

◆ download_file()

DownloadResult pulp::runtime::download_file ( const DownloadRequest & request,
const DownloadProgressFn & on_progress = {},
const CancelToken * cancel = nullptr )

Blocking streaming download.

Writes to <dest>.part, verifies sha256 against expected_sha256, then atomically renames to dest. A request with no expected digest is refused before any network or disk activity unless it sets allow_unverified. On cancel/error the .part file is left in place so a later call with resume = true continues it.

◆ ed25519_keypair_from_seed()

std::optional< Ed25519KeyPair > pulp::runtime::ed25519_keypair_from_seed ( const uint8_t * seed_32,
size_t seed_size )

Derive a deterministic Ed25519 keypair from a 32-byte seed.

Useful for test vectors and for reproducing a key from a backed-up seed.

◆ ed25519_keypair_generate()

std::optional< Ed25519KeyPair > pulp::runtime::ed25519_keypair_generate ( )

Generate a fresh Ed25519 keypair using mbedTLS CTR-DRBG for entropy.

Returns std::nullopt on RNG failure (rare; reserved for hardware-RNG failure on locked-down platforms).

◆ ed25519_sign()

std::optional< std::vector< uint8_t > > pulp::runtime::ed25519_sign ( const uint8_t * private_key_64,
size_t private_key_size,
const uint8_t * message,
size_t message_size )

Sign a message with an Ed25519 private key (64-byte NaCl-form).

Returns the 64-byte detached signature, or std::nullopt on input size validation failure.

◆ ed25519_verify()

bool pulp::runtime::ed25519_verify ( const uint8_t * public_key_32,
size_t public_key_size,
const uint8_t * signature_64,
size_t signature_size,
const uint8_t * message,
size_t message_size )

Verify a 64-byte detached signature against a message + 32-byte public key.

Returns true iff the signature is authentic. Returns false on any input- size mismatch (defense in depth — callers should still range-check).

◆ Err()

template<typename E>
pulp::runtime::Err ( E ) ->Err< E >

◆ evaluate()

std::optional< double > pulp::runtime::evaluate ( std::string_view expression,
const std::map< std::string, double > & variables = {} )

Evaluate a math expression string.

Variables can be provided as a name→value map. Returns nullopt on parse error.

Examples: evaluate("2 + 3") → 5.0 evaluate("sin(pi / 2)") → 1.0 evaluate("x * 2 + 1", {{"x", 3.0}}) → 7.0 evaluate("min(a, b)", {{"a", 5}, {"b", 3}}) → 3.0

◆ evaluate_runtime_budget()

RuntimeBudgetDecision pulp::runtime::evaluate_runtime_budget ( const RuntimeBudgetRequest & request,
const RuntimeBudgetPolicy & policy = {} )
inlinenoexcept

◆ file_identity()

FileIdentity pulp::runtime::file_identity ( std::string_view path)
noexcept

◆ find_model()

const ModelEntry * pulp::runtime::find_model ( const std::vector< ModelEntry > & registry,
std::string_view model_id )

Find a model by id in a caller-supplied registry/catalog. Returns nullptr if absent.

◆ form_decode()

std::string pulp::runtime::form_decode ( std::string_view s)

Reverse of form_encode. + decodes to space.

◆ form_encode()

std::string pulp::runtime::form_encode ( std::string_view s)

application/x-www-form-urlencoded style — space → +, then percent-encode everything else.

◆ format_diff()

std::string pulp::runtime::format_diff ( const std::vector< DiffEntry > & diff)

Format a diff as a unified diff string (with +/- prefixes).

◆ generate_prime()

uint64_t pulp::runtime::generate_prime ( int bits = 32)

Generate a random prime of the given bit length.

Returns 0 on failure.

◆ get_env()

std::optional< std::string > pulp::runtime::get_env ( std::string_view name)
inline

◆ get_system_info()

const SystemInfo & pulp::runtime::get_system_info ( )

Query system information (cached after first call).

◆ gmtime_utc()

std::tm pulp::runtime::gmtime_utc ( std::time_t value)
inline

◆ gzip_compress() [1/2]

std::optional< std::vector< uint8_t > > pulp::runtime::gzip_compress ( const uint8_t * data,
size_t size,
int level = 6 )

Compress data into an RFC 1952 gzip stream.

◆ gzip_compress() [2/2]

std::optional< std::vector< uint8_t > > pulp::runtime::gzip_compress ( std::string_view data,
int level = 6 )

Convenience: compress a string into an RFC 1952 gzip stream.

◆ gzip_decompress()

std::optional< std::vector< uint8_t > > pulp::runtime::gzip_decompress ( const uint8_t * data,
size_t size,
size_t max_output = kDefaultMaxDecompressOutput )

Decompress a gzip (RFC 1952) or zlib (RFC 1950) stream.

Fails closed (returns nullopt) if the decompressed output would exceed max_output.

◆ gzip_decompress_string()

std::optional< std::string > pulp::runtime::gzip_decompress_string ( const uint8_t * data,
size_t size )

Convenience: decompress a gzip (RFC 1952) or zlib (RFC 1950) stream into a string.

◆ hex_encode() [1/2]

std::string pulp::runtime::hex_encode ( const std::vector< uint8_t > & bytes)
inline

◆ hex_encode() [2/2]

std::string pulp::runtime::hex_encode ( const uint8_t * data,
size_t size )
inline

Lowercase-hex encode raw bytes.

Header-only; the one place callers should reach for bytes→hex (e.g. key/signature fingerprints) instead of re-rolling a nibble loop.

◆ hmac_sha1()

std::optional< std::vector< uint8_t > > pulp::runtime::hmac_sha1 ( const uint8_t * key,
size_t key_size,
const uint8_t * data,
size_t data_size )

Compute HMAC-SHA1(key, data).

Returns 20-byte tag on success, std::nullopt on mbedTLS failure (see hmac_sha256). Legacy use (e.g., AWS Signature v2). Vectors: RFC 2202 (HMAC-SHA-1).

◆ hmac_sha256() [1/2]

std::optional< std::vector< uint8_t > > pulp::runtime::hmac_sha256 ( const uint8_t * key,
size_t key_size,
const uint8_t * data,
size_t data_size )

Compute HMAC-SHA256(key, data).

Returns 32-byte tag on success, std::nullopt if the underlying mbedTLS context fails (alloc / bad input / build-config mismatch — rare in practice). Vectors: RFC 4231 (HMAC-SHA-256).

◆ hmac_sha256() [2/2]

std::optional< std::vector< uint8_t > > pulp::runtime::hmac_sha256 ( std::string_view key,
std::string_view data )

◆ hostname()

std::string pulp::runtime::hostname ( )

Get the hostname.

◆ http_download()

bool pulp::runtime::http_download ( std::string_view url,
std::string_view output_path,
int timeout_seconds = 60 )

Download a file from a URL to a local path. Returns true on success.

◆ http_get()

HttpResponse pulp::runtime::http_get ( std::string_view url,
int timeout_seconds = 30 )

Perform an HTTP GET request.

◆ http_post()

HttpResponse pulp::runtime::http_post ( std::string_view url,
std::string_view body,
std::string_view content_type = "application/json",
int timeout_seconds = 30 )

Perform an HTTP POST request with a body.

◆ http_request()

HttpResponse pulp::runtime::http_request ( const HttpRequest & request)

Perform an HTTP request. GET and POST are supported.

◆ install_model()

InstallModelResult pulp::runtime::install_model ( const ModelEntry & model,
std::string_view subsystem,
const std::function< bool(const struct DownloadProgress &)> & on_progress = {},
const CancelToken * cancel = nullptr,
const std::vector< std::pair< std::string, std::string > > & headers = {},
const std::filesystem::path & pulp_home_override = {},
bool allow_unverified = false )

Download model's checkpoint into <home>/<subsystem>/models/<id>/ (streaming, resumable, sha256-verified), then write the install metadata so read_installed_model/ activate_model see it.

on_progress returning false (or a cancelled token) aborts and keeps the partial for a later resume. Auth headers (e.g. HuggingFace token) optional. An asset whose registry entry carries no sha256 is refused unless allow_unverified is set; a CLI or UI surfaces that as an explicit --unverified style opt-in.

◆ is_in_no_alloc_scope()

bool pulp::runtime::is_in_no_alloc_scope ( )
noexcept
Returns
true if at least one ScopedNoAlloc is alive on the calling thread AND no ScopedAllocAllowed is currently suspending the contract. false in NDEBUG builds always.

◆ is_prime()

bool pulp::runtime::is_prime ( uint64_t n,
int rounds = 40 )

Test if a number is probably prime (Miller-Rabin).

rounds controls accuracy (default 40 = negligible false positive rate).

◆ is_safe_relative_path()

bool pulp::runtime::is_safe_relative_path ( const std::filesystem::path & path)
inline

True only if path is safe to join beneath a destination directory: a non-empty relative path with no root name (C:, \\server), no root directory (/ or \\endiskip), and no component that is empty, .

, .., or contains \\endiskip, : or NUL.

◆ is_valid_ipv4()

bool pulp::runtime::is_valid_ipv4 ( std::string_view address)

Parse and validate an IPv4 address.

◆ is_within_directory()

bool pulp::runtime::is_within_directory ( const std::filesystem::path & directory,
const std::filesystem::path & candidate )
inline

True if candidate, compared lexically after normalization, is directory itself or lies beneath it.

An empty directory contains nothing. Use it after joining a screened relative path onto its destination, as a second line of defence.

◆ list_models()

ModelListResult pulp::runtime::list_models ( const std::vector< ModelEntry > & registry,
std::string_view subsystem,
const std::filesystem::path & pulp_home_override = {} )

◆ local_ipv4_address()

std::string pulp::runtime::local_ipv4_address ( )

Get the primary local IPv4 address (first non-loopback).

◆ local_ipv4_addresses()

std::vector< std::string > pulp::runtime::local_ipv4_addresses ( )

Get all local IPv4 addresses (excluding loopback).

◆ localtime_local()

std::tm pulp::runtime::localtime_local ( std::time_t value)
inline

◆ log()

template<typename... Args>
void pulp::runtime::log ( LogLevel level,
std::format_string< Args... > fmt,
Args &&... args )

◆ log_debug()

template<typename... Args>
void pulp::runtime::log_debug ( std::format_string< Args... > fmt,
Args &&... args )

◆ log_error()

template<typename... Args>
void pulp::runtime::log_error ( std::format_string< Args... > fmt,
Args &&... args )

◆ log_info()

template<typename... Args>
void pulp::runtime::log_info ( std::format_string< Args... > fmt,
Args &&... args )

◆ log_tracing_reminder()

void pulp::runtime::log_tracing_reminder ( )

Emit — at most once for the whole process — a single dev-build reminder that Perfetto tracing is compiled in.

In a PULP_TRACING=ON build this logs one log_info line the first time it is called; in the default OFF build it is a no-op that logs nothing. Safe to call unconditionally from app/plugin startup (no #ifdef at the call site).

◆ log_warn()

template<typename... Args>
void pulp::runtime::log_warn ( std::format_string< Args... > fmt,
Args &&... args )

◆ log_with_category()

template<typename... Args>
void pulp::runtime::log_with_category ( std::string_view category,
LogLevel level,
std::format_string< Args... > fmt,
Args &&... args )

Log with an explicit category (a subsystem tag such as "audio" or "net").

◆ machine_id()

std::string pulp::runtime::machine_id ( )

Generate a machine-specific fingerprint (deterministic per machine).

Uses hardware identifiers (MAC address, CPU info, hostname) hashed with SHA-256.

◆ make_activity_channel()

template<std::size_t LaneCount>
SharedActivityChannel< LaneCount > pulp::runtime::make_activity_channel ( )

◆ make_scope_guard()

template<typename F>
ScopeGuard< F > pulp::runtime::make_scope_guard ( F && fn)

◆ md5() [1/2]

std::vector< uint8_t > pulp::runtime::md5 ( const uint8_t * data,
size_t size )

Compute MD5 hash. Returns 16-byte digest. (Legacy use only.).

◆ md5() [2/2]

std::vector< uint8_t > pulp::runtime::md5 ( std::string_view data)

◆ md5_hex()

std::string pulp::runtime::md5_hex ( std::string_view data)

Compute MD5 hash as hex string (32 chars).

◆ migrate_v1_to_v2()

std::optional< std::string > pulp::runtime::migrate_v1_to_v2 ( std::string_view v1_license_key,
std::string_view v1_public_key_pem,
const uint8_t * v2_secret_32,
size_t v2_secret_size )

Re-encode a v1 license key as v2 using the supplied 32-byte secret.

The v1 RSA-signature is verified before re-emission (so a v1 key that fails verification cannot be "migrated" to a v2 key that does pass). The exact LicenseInfo (product_id, email, machine_id, edition, issued, expiry) is preserved.

Use case: a server holds historical v1 keys; on next renewal the user downloads a freshly-issued v2 key. For self-service migration the plugin itself can call this helper with the locally-cached v2 secret.

◆ model_install_path()

std::filesystem::path pulp::runtime::model_install_path ( std::string_view subsystem,
std::string_view model_id,
const std::filesystem::path & pulp_home_override = {} )

◆ model_state_path()

std::filesystem::path pulp::runtime::model_state_path ( std::string_view subsystem,
const std::filesystem::path & pulp_home_override = {} )

◆ no_alloc_allowed_depth()

int pulp::runtime::no_alloc_allowed_depth ( )
noexcept

Depth of nested ScopedAllocAllowed instances on the current thread.

Diagnostics / tests only. 0 in NDEBUG builds always.

◆ no_alloc_scope_depth()

int pulp::runtime::no_alloc_scope_depth ( )
noexcept

Depth of nested ScopedNoAlloc instances on the current thread.

Mostly useful for diagnostics and tests; is_in_no_alloc_scope() covers the common "are we in one?" check. Not affected by ScopedAllocAllowed — it counts guards, not the suspension.

◆ Ok()

template<typename T>
pulp::runtime::Ok ( T ) ->Ok< T >

◆ parse_query()

std::vector< std::pair< std::string, std::string > > pulp::runtime::parse_query ( std::string_view query)

Parse a URL query string into key/value pairs.

Treats & and ; as separators. Leading ? is tolerated. Values without = produce pairs with empty value. Values are NOT decoded — call form_decode() per-component if needed.

◆ percent_decode()

std::string pulp::runtime::percent_decode ( std::string_view s)

Decode percent-escapes — %20 → space, %2F → /.

Invalid escape sequences are passed through unchanged.

◆ percent_encode()

std::string pulp::runtime::percent_encode ( std::string_view s)

Percent-encode s per RFC 3986 — unreserved characters (A-Z a-z 0-9 - _ .

~) pass through untouched. Spaces become %20, not + (callers that want form-style encoding should call form_encode instead).

◆ read_active_model_id()

std::string pulp::runtime::read_active_model_id ( std::string_view subsystem,
const std::filesystem::path & pulp_home_override = {} )

◆ read_installed_model()

InstalledModelRecord pulp::runtime::read_installed_model ( std::string_view subsystem,
std::string_view model_id,
const std::filesystem::path & pulp_home_override = {} )

◆ realtime_resource_slot_publish_succeeded()

bool pulp::runtime::realtime_resource_slot_publish_succeeded ( RealtimeResourceSlotPublishStatus status)
constexprnoexcept

◆ remove_model()

bool pulp::runtime::remove_model ( std::string_view subsystem,
std::string_view model_id,
std::string & error,
const std::filesystem::path & pulp_home_override = {} )

Delete an installed model's files + metadata.

Clears the active selection if it pointed here. Returns false (with error set) on a filesystem error or invalid input, and false (no error) when nothing was present to remove; true only when files/metadata were deleted.

◆ resolve_checkpoint_url()

std::string pulp::runtime::resolve_checkpoint_url ( const std::string & checkpoint_ref)

Resolve a checkpoint_ref to a direct download URL.

"hf://user/repo/file" → "https://huggingface.co/user/repo/resolve/main/file". Rejects control bytes, .. segments (in both the user/repo and file parts), and percent-encoded path content. Passes http(s):// URLs through.

◆ resolve_pulp_home()

std::filesystem::path pulp::runtime::resolve_pulp_home ( const std::filesystem::path & override_path = {})

◆ resolve_redirect()

ResolvedRedirect pulp::runtime::resolve_redirect ( const std::string & current_scheme_host_port,
const std::string & current_path,
const std::string & location )

Resolve an absolute, host-absolute, or path-relative redirect location against the current origin + path.

Refuses a hop from https to http so a transfer that started encrypted cannot be downgraded mid-flight (an http origin may upgrade to https).

◆ run_process()

std::optional< ProcessResult > pulp::runtime::run_process ( std::string_view executable,
const std::vector< std::string > & args = {},
std::string_view working_dir = "",
int timeout_ms = 0 )

Launch a child process and wait for it to complete.

Returns nullopt if the process could not be started.

◆ secure_random_bytes()

std::optional< std::vector< uint8_t > > pulp::runtime::secure_random_bytes ( size_t size)

Generate bytes from the runtime's entropy-seeded CTR-DRBG.

Returns nullopt when entropy initialization or generation fails.

◆ secure_zero_memory()

void pulp::runtime::secure_zero_memory ( void * data,
size_t size )
noexcept

Overwrite sensitive bytes through volatile stores so the wipe is not removed as a dead store when the containing object is destroyed.

◆ set_log_sink()

LogSink pulp::runtime::set_log_sink ( LogSink sink)
inline

Install sink as the process-wide log sink and return the previous one (empty if none).

Passing an empty function removes the sink. The swap is thread-safe: a record being delivered to the old sink finishes there, and the old sink may still run briefly on other threads after this returns.

◆ sha1() [1/2]

std::vector< uint8_t > pulp::runtime::sha1 ( const uint8_t * data,
size_t size )

Compute SHA-1 hash.

Returns 20-byte digest. (Legacy protocols only — e.g., WebSocket handshake per RFC 6455.)

◆ sha1() [2/2]

std::vector< uint8_t > pulp::runtime::sha1 ( std::string_view data)

◆ sha256() [1/2]

std::vector< uint8_t > pulp::runtime::sha256 ( const uint8_t * data,
size_t size )

Compute SHA-256 hash.

Returns 32-byte digest.

On arm64 targets with the ARMv8 SHA-2 extension (every Apple silicon Mac and iOS device) the blocks run through the SHA256H/SHA256H2 instructions, about ten times faster than the portable rounds; every other target, x86_64 included, uses the portable rounds. Both produce identical digests.

◆ sha256() [2/2]

std::vector< uint8_t > pulp::runtime::sha256 ( std::string_view data)

◆ sha256_file_hex()

std::optional< std::string > pulp::runtime::sha256_file_hex ( const std::filesystem::path & path,
std::uint64_t max_bytes )

Stream a file through SHA-256 without retaining its contents in memory.

Returns nullopt when the file cannot be read or exceeds max_bytes.

◆ sha256_hex() [1/2]

std::string pulp::runtime::sha256_hex ( const uint8_t * data,
size_t size )

Compute SHA-256 hash as hex string (64 chars).

◆ sha256_hex() [2/2]

std::string pulp::runtime::sha256_hex ( std::string_view data)

◆ sieve_primes()

std::vector< uint32_t > pulp::runtime::sieve_primes ( uint32_t limit)

Generate the first N primes via sieve of Eratosthenes.

◆ simd_abs() [1/2]

void pulp::runtime::simd_abs ( const double * a,
double * dst,
std::size_t count )
inline

◆ simd_abs() [2/2]

void pulp::runtime::simd_abs ( const float * a,
float * dst,
std::size_t count )
inline

◆ simd_add() [1/2]

void pulp::runtime::simd_add ( const double * a,
const double * b,
double * dst,
std::size_t count )
inline

◆ simd_add() [2/2]

void pulp::runtime::simd_add ( const float * a,
const float * b,
float * dst,
std::size_t count )
inline

◆ simd_add_scaled() [1/2]

void pulp::runtime::simd_add_scaled ( const double * a,
double scalar,
double * dst,
std::size_t count )
inline

◆ simd_add_scaled() [2/2]

void pulp::runtime::simd_add_scaled ( const float * a,
float scalar,
float * dst,
std::size_t count )
inline

◆ simd_clamp() [1/2]

void pulp::runtime::simd_clamp ( const double * a,
double lo,
double hi,
double * dst,
std::size_t count )
inline

◆ simd_clamp() [2/2]

void pulp::runtime::simd_clamp ( const float * a,
float lo,
float hi,
float * dst,
std::size_t count )
inline

◆ simd_double_lanes()

std::size_t pulp::runtime::simd_double_lanes ( )
inline

◆ simd_float_lanes()

std::size_t pulp::runtime::simd_float_lanes ( )
inline

◆ simd_fma() [1/2]

void pulp::runtime::simd_fma ( const double * a,
const double * b,
const double * c,
double * dst,
std::size_t count )
inline

◆ simd_fma() [2/2]

void pulp::runtime::simd_fma ( const float * a,
const float * b,
const float * c,
float * dst,
std::size_t count )
inline

◆ simd_mul() [1/2]

void pulp::runtime::simd_mul ( const double * a,
const double * b,
double * dst,
std::size_t count )
inline

◆ simd_mul() [2/2]

void pulp::runtime::simd_mul ( const float * a,
const float * b,
float * dst,
std::size_t count )
inline

◆ simd_reduce_add() [1/2]

double pulp::runtime::simd_reduce_add ( const double * data,
std::size_t count )
inline

◆ simd_reduce_add() [2/2]

float pulp::runtime::simd_reduce_add ( const float * data,
std::size_t count )
inline

◆ simd_reduce_max() [1/2]

double pulp::runtime::simd_reduce_max ( const double * data,
std::size_t count )
inline

◆ simd_reduce_max() [2/2]

float pulp::runtime::simd_reduce_max ( const float * data,
std::size_t count )
inline

◆ simd_reduce_min() [1/2]

double pulp::runtime::simd_reduce_min ( const double * data,
std::size_t count )
inline

◆ simd_reduce_min() [2/2]

float pulp::runtime::simd_reduce_min ( const float * data,
std::size_t count )
inline

◆ simd_scale() [1/2]

void pulp::runtime::simd_scale ( const double * a,
double scalar,
double * dst,
std::size_t count )
inline

◆ simd_scale() [2/2]

void pulp::runtime::simd_scale ( const float * a,
float scalar,
float * dst,
std::size_t count )
inline

◆ simd_set() [1/2]

void pulp::runtime::simd_set ( double value,
double * dst,
std::size_t count )
inline

◆ simd_set() [2/2]

void pulp::runtime::simd_set ( float value,
float * dst,
std::size_t count )
inline

◆ text_diff()

std::vector< DiffEntry > pulp::runtime::text_diff ( std::string_view from,
std::string_view to )

Compute a line-based diff between two strings.

Returns a sequence of operations to transform from into to.

◆ to_json() [1/2]

std::string pulp::runtime::to_json ( const ActivateModelResult & result)

◆ to_json() [2/2]

std::string pulp::runtime::to_json ( const ModelListResult & result)

◆ to_string()

const char * pulp::runtime::to_string ( RuntimeBudgetAction action)
inlinenoexcept

◆ total_memory_mb()

uint64_t pulp::runtime::total_memory_mb ( )

Total physical memory in MB (convenience).

◆ tr() [1/2]

std::string pulp::runtime::tr ( std::string_view key)
inline

Convenience: translate a key using the global instance.

◆ tr() [2/2]

std::string pulp::runtime::tr ( std::string_view key,
const std::vector< std::string > & args )
inline

Convenience: translate with arguments.

◆ tracing_reminder_first_time()

bool pulp::runtime::tracing_reminder_first_time ( std::atomic< bool > & already_emitted)

One-shot gate for the "tracing compiled in" reminder.

Returns true exactly once per already_emitted flag (on its first call) and false thereafter, so a reminder can be logged a single time even across threads and multiple plugin instances. Config-independent so the gate is unit-testable in the default OFF build.

◆ x25519_keypair_from_private_key()

std::optional< X25519KeyPair > pulp::runtime::x25519_keypair_from_private_key ( const uint8_t * private_key_32,
size_t private_key_size )

Recover the public key for an existing 32-byte private scalar.

Deterministic — this is how a keypair is reconstituted from a stored or backed-up secret, and how RFC 7748 test vectors are checked.

◆ x25519_keypair_generate()

std::optional< X25519KeyPair > pulp::runtime::x25519_keypair_generate ( )

Generate a fresh X25519 keypair using mbedTLS CTR-DRBG for entropy.

Returns std::nullopt on RNG failure (rare; reserved for hardware-RNG failure on locked-down platforms).

◆ x25519_shared_secret()

std::optional< std::vector< uint8_t > > pulp::runtime::x25519_shared_secret ( const uint8_t * private_key_32,
size_t private_key_size,
const uint8_t * peer_public_key_32,
size_t peer_public_key_size )

Compute the raw X25519 shared secret between our private key and a peer's public key.

Returns std::nullopt on an input-size mismatch, and on an all-zero result — that output means the peer supplied a small-order point, so the "shared" secret would be a value the peer already knew (RFC 7748 §6.1).

The result is NOT a key. X25519 output is a curve point, not uniformly distributed bytes, and using it directly as an AES key is a real weakness. Run it through a KDF first — hmac_sha256 above is sufficient when the salt and context string are fixed by the format.

◆ xml_generate()

std::string pulp::runtime::xml_generate ( std::string_view root_name,
const std::vector< std::pair< std::string, std::string > > & elements )

Generate a simple XML string from key-value pairs.

Creates: <root><key1>value1</key1><key2>value2</key2></root>

◆ zlib_compress()

std::optional< std::vector< uint8_t > > pulp::runtime::zlib_compress ( const uint8_t * data,
size_t size,
int level = 6 )

Compress data into an RFC 1950 zlib stream.

◆ zlib_decompress()

std::optional< std::vector< uint8_t > > pulp::runtime::zlib_decompress ( const uint8_t * data,
size_t size,
size_t max_output = kDefaultMaxDecompressOutput )

Decompress exactly one RFC 1950 zlib stream.

Unlike gzip_decompress(), this rejects RFC 1952 gzip wrapping and trailing bytes. It allocates its output, so it must never run on the audio thread.

◆ zlib_decompress_exact()

std::optional< std::string > pulp::runtime::zlib_decompress_exact ( const uint8_t * data,
size_t size,
size_t expected_size )

Decompress one RFC 1950 zlib stream whose inflated size is known in advance (an embedded asset that recorded it at build time) straight into a string of exactly that size, with no growth or second copy.

Returns nullopt unless the stream inflates to exactly expected_size bytes, passes its Adler-32 check and consumes every input byte. It allocates its output, so it must never run on the audio thread.

Variable Documentation

◆ ed25519_private_key_size

size_t pulp::runtime::ed25519_private_key_size = 64
inlineconstexpr

◆ ed25519_public_key_size

size_t pulp::runtime::ed25519_public_key_size = 32
inlineconstexpr

Ed25519 key sizes (RFC 8032 §5.1).

◆ ed25519_seed_size

size_t pulp::runtime::ed25519_seed_size = 32
inlineconstexpr

◆ ed25519_signature_size

size_t pulp::runtime::ed25519_signature_size = 64
inlineconstexpr

◆ kCurrentLicenseFormat

LicenseFormatVersion pulp::runtime::kCurrentLicenseFormat
inlineconstexpr
Initial value:
=
@ V2
"v2." + base64url(IV || AES-256-GCM(json) || tag)
Definition license.hpp:29

Latest format emitted by LicenseGenerator.

Bumped each time the on-disk format changes; old formats stay parseable.

◆ kDefaultLogCategory

std::string_view pulp::runtime::kDefaultLogCategory = "pulp"
inlineconstexpr

Category used by log_info and the other level helpers.

◆ kDefaultMaxDecompressOutput

size_t pulp::runtime::kDefaultMaxDecompressOutput = 256u * 1024u * 1024u
inlineconstexpr

Default ceiling on total decompressed output (bytes).

Decompression is a bomb vector — a small, highly compressible input can inflate to gigabytes and OOM-kill the process — so callers on untrusted paths (appcast feeds, design-import bundles) get a bounded default. 256 MiB is far above any real payload Pulp handles while making a bomb fail closed.

◆ kTracingEnabled

bool pulp::runtime::kTracingEnabled = false
inlineconstexpr

True only in a PULP_TRACING=ON build. Every shipping/default build is false.

◆ x25519_private_key_size

size_t pulp::runtime::x25519_private_key_size = 32
inlineconstexpr

◆ x25519_public_key_size

size_t pulp::runtime::x25519_public_key_size = 32
inlineconstexpr

X25519 key and output sizes (RFC 7748 §5).

◆ x25519_shared_secret_size

size_t pulp::runtime::x25519_shared_secret_size = 32
inlineconstexpr