carb#

namespace carb#

The main Carbonite namespace.

Namespace for all low level Carbonite functionality.

Classes#

Allocator: A class implementing the ' Allocator ' C++ Named Requirement.
Deleter: Allocated object deleter helper class.
EmptyMemberPair: Attempts to invoke the Empty Member Optimization by inheriting from the First element if possible, which, if empty will eliminate the storage necessary for an empty class; the Second element is always stored as a separate member. The First element is inherited from if it is an empty class / struct and is not declared final .
EventSubscribers: A class that manages subscribers.
FrameworkInitializerForBindings: A helper class used by CARB_BINDINGS() to acquire and release the Framework for a binding.
IObject: Reference-counted object base.
ObjectPtr: Smart pointer type for ref counting IObject .
RString: Carbonite registered strings.
RStringKey: A registered string key.
RStringU: Case-insensitive registered string.
RStringUKey: A case-insensitive registered string key.
UseCarbAllocatorAligned: An object can inherit from this class in order to use Carbonite allocation functions for creation/deletion.

Enumerations#

uint64_t AcquireInterfaceFlags: Flags for use with carb::AcquireInterfaceOptions .
uint32_t BindingType: An enum that describes a binding registration for carb::Framework::registerScriptBinding() .
InitPolicy: Policy directing how the smart pointer is initialized from from raw pointer.
int32_t LoadPluginResult: Result of loading a plugin. Used by carb::Framework::loadPlugin . Non-negative values indicated success.
PluginHotReload: Defines the plugin hot reloading (auto reload) behavior.
PluginReloadState: Lets clients of a plugin know both just before and just after that the plugin is being reloaded.
PrefetchLevel: A prefetch level hint to pass to CARB_PREFETCH()
RStringOp: Operations for RString (and variant classes) constructor.

Functions#

carb::Framework * acquireFramework(const char *appName, Version frameworkVersion=kFrameworkVersion): Acquire the Carbonite framework for an application.
Framework * acquireFrameworkAndRegisterBuiltins(const OmniCoreStartArgs *args=nullptr): Main acquisition of the Carbonite Framework for Clients (applications and plugins).
Framework * acquireFrameworkForBindings(const char *scriptLanguage): Acquires the Carbonite Framework for a script binding.
InterfaceType * acquireInterfaceForBindings(const char *pluginName=nullptr): A helper function for Framework::tryAcquireInterface() that attempts to load plugins if not found.
InterfaceType * acquireInterfaceFromLibraryForBindings(const char *libraryPath): Helper for Framework::tryAcquireInterfaceFromLibrary() that throws on error.
void * allocate(size_t size, size_t align=0) noexcept: Allocates a block of memory.
ObjectPtr< T > borrowObject(T *other): Helper function to create carb::ObjectPtr from a carb::IObject pointer by "borrowing" the pointer; that is, by increasing the reference count.
const char * carbGetSdkVersion(): Retrieves the Carbonite SDK version string,.
void configureFramework(const StartupFrameworkDesc &params): Configures the framework given a slew of input parameters.
void deallocate(void *p) noexcept: Deallocates a block of memory previously allocated with allocate() .
void deleteHandler(T *ptr): Default handler for carb::IObject reaching zero references, which calls delete .
bool findPlugins(const FindPluginsArgs &inArgs) noexcept: Helper function to find plugins in a given list of search paths.
constexpr uint64_t fnv1aHash(const char *str, std::size_t n, uint64_t hash=kFnvBasis): Compile-time FNV-1a 64-bit hash, use with CARB_HASH_STRING macro.
constexpr Version fromHexVersion(uint32_t hexver) noexcept: Converts a hex-version to a Version struct.
InterfaceT * getCachedInterface(): Retrieves the specified interface as if from Framework::tryAcquireInterface() and caches it for fast retrieval.
InterfaceType * getCachedInterfaceForBindings(): A helper function for carb::getCachedInterface() that throws on error.
Framework * getFramework(): Gets the Carbonite framework.
uint64_t hashBuffer(const void *buffer, size_t length, uint64_t hash=kFnvBasis): Runtime FNV-1a 64-bit byte hash.
constexpr uint64_t hashCombine(uint64_t hash1, uint64_t hash2) noexcept: Combines two hashes producing better collision avoidance than XOR.
uint64_t hashLowercaseBuffer(const void *buffer, size_t len, uint64_t hash=kFnvBasis): Runtime FNV-1a 64-bit lower-case byte hash (as if the bytes had been converted using tolower() ).
uint64_t hashLowercaseString(const char *str, uint64_t hash=kFnvBasis): Runtime FNV-1a 64-bit lower-case string hash (as if the string had been converted using tolower() ).
size_t hashPair(T1 t1, T2 t2): A helper function for combining two hash values.
constexpr uint64_t hashScalar(const T &type, uint64_t hash=kFnvBasis): Runtime FNV-1a 64-bit hash of a scalar type.
uint64_t hashString(const char *str, uint64_t hash=kFnvBasis): Runtime FNV-1a 64-bit string hash.
uint64_t hashUppercaseBuffer(const void *buffer, size_t len, uint64_t hash=kFnvBasis): Runtime FNV-1a 64-bit upper-case byte hash (as if the bytes had been converted using toupper() ).
uint64_t hashUppercaseString(const char *str, uint64_t hash=kFnvBasis): Runtime FNV-1a 64-bit upper-case string hash (as if the string had been converted using toupper() ).
bool isFrameworkValid(): Returns true if the Carbonite framework has been created and is still alive. Creation happens at the first carb::acquireFramework() call and ends at any carb::releaseFramework() call.
bool isVersionSemanticallyCompatible(const char *name, const Version &minimum, const Version &candidate): Checks two versions to see if they are semantically compatible.
void loadFrameworkConfiguration(const StartupFrameworkDesc &params): Loads the framework configuration based on a slew of input parameters.
void loadPluginsFromPattern(const char *pluginNamePattern, const char *const *searchPaths=nullptr, size_t searchPathCount=0): Simple plugin loading function wrapper that loads plugins matching a single pattern.
void loadPluginsFromPatterns(const char *const *pluginNamePatterns, size_t pluginNamePatternCount, const char *const *searchPaths=nullptr, size_t searchPathCount=0): Simple plugin loading function wrapper that loads plugins matching multiple patterns.
bool operator!=(const T *lhs, const ObjectPtr< U > &rhs) noexcept: Checks inequality of an ObjectPtr type and a raw pointer.
bool operator!=(std::nullptr_t, const ObjectPtr< T > &rhs) noexcept: Checks inequality of an ObjectPtr type and nullptr.
constexpr bool operator!=(const Version &lhs, const Version &rhs) noexcept: Inequality operator.
bool operator!=(const ObjectPtr< T > &lhs, const ObjectPtr< U > &rhs) noexcept: Checks inequality of two ObjectPtr types.
bool operator!=(const ObjectPtr< T > &lhs, const U *rhs) noexcept: Checks inequality of an ObjectPtr type and a raw pointer.
bool operator!=(const ObjectPtr< T > &lhs, std::nullptr_t) noexcept: Checks inequality of an ObjectPtr type and nullptr.
constexpr bool operator<(const Version &lhs, const Version &rhs) noexcept: Less-than comparison operator.
::std::basic_ostream< CharT, Traits > & operator<<(::std::basic_ostream< CharT, Traits > &o, const RStringUKey &s): Global stream output operator for RStringUKey .
::std::basic_ostream< CharT, Traits > & operator<<(::std::basic_ostream< CharT, Traits > &o, const RStringKey &s): Global stream output operator for RStringKey .
::std::basic_ostream< CharT, Traits > & operator<<(::std::basic_ostream< CharT, Traits > &o, const RString &s): Global stream output operator for RString .
::std::basic_ostream< CharT, Traits > & operator<<(::std::basic_ostream< CharT, Traits > &o, const RStringU &s): Global stream output operator for RStringU .
constexpr bool operator<=(const Version &lhs, const Version &rhs) noexcept: Less-than-or-equal comparison operator.
bool operator==(std::nullptr_t, const ObjectPtr< T > &rhs) noexcept: Checks equality of an ObjectPtr type and nullptr.
constexpr bool operator==(const Version &lhs, const Version &rhs) noexcept: Equality operator.
bool operator==(const ObjectPtr< T > &lhs, const ObjectPtr< U > &rhs) noexcept: Checks equality of two ObjectPtr types.
bool operator==(const ObjectPtr< T > &lhs, std::nullptr_t) noexcept: Checks equality of an ObjectPtr type and nullptr.
bool operator==(const ObjectPtr< T > &lhs, const U *rhs) noexcept: Checks equality of an ObjectPtr type and a raw pointer.
bool operator==(const T *lhs, const ObjectPtr< U > &rhs) noexcept: Checks equality of an ObjectPtr type and a raw pointer.
void pluginDeinitialize(): Function called automatically at plugin shutdown to de-initialize utilities within each plugin.
void pluginInitialize(): Function called automatically at plugin startup to initialize utilities within each plugin.
void quickReleaseFrameworkAndTerminate(int exitCode): Releases the Carbonite framework immediately and exits the process, without running C/C++ atexit() registered functions or static destructors.
void * reallocate(void *p, size_t size, size_t align=0) noexcept: Reallocates a block of memory previously allocated with allocate() .
void releaseFramework(): Releases the Carbonite framework immediately.
void releaseFrameworkAndDeregisterBuiltins(): This function releases the Carbonite Framework .
void releaseFrameworkAndShutdown(): Unloads all plugins and shuts down the Carbonite Framework without terminating the process.
void releaseFrameworkAndTerminate(int exitCode): Releases the Carbonite framework immediately and exits the process.
void releaseFrameworkForBindings(): Releases the Carbonite Framework for a script binding.
void resetCachedInterface(): Resets any previously-cached interface of the given type and allows it to be acquired again.
void shutdownFramework(): Tears down the Carbonite framework.
void startupFramework(const StartupFrameworkDesc &params): Starts/Configures the framework given a slew of input parameters.
ObjectPtr< T > stealObject(T *other): Helper function to create carb::ObjectPtr from a carb::IObject pointer by "stealing" the pointer; that is, without increasing the reference count.
constexpr uint32_t toHexVersion(carb::Version ver) noexcept: Converts a Version struct to a hex-version.
constexpr unsigned char tolower(unsigned char c): A fast table-based implementation of std::tolower for ASCII characters only.
constexpr unsigned char toupper(unsigned char c): A fast table-based implementation of std::toupper for ASCII characters only.
auto wrapInterfaceFunction(ReturnType(*InterfaceType::*p)(Args…)) -> std::function< ReturnType(InterfaceType &, Args…)>: Wraps an interface function into a std::function<> .
auto wrapInterfaceFunction(const InterfaceType *c, ReturnType(*InterfaceType::*p)(Args…)) -> std::function< ReturnType(Args…)>: Wraps an interface function into a std::function<> .

Namespaces#

assert: Namespace for all assertion checking helpers and interfaces.
assets: Namespace for carb.assets.plugin and related utilities.
clock: Namespace for clock utilities.
container: Carbonite container classes.
cpp: Namespace for C++ standard library types after C++14 implemented and usable by C++14 compilers.
crashreporter: Namespace for the crash reporter.
delegate: Namespace for Carbonite delegate implementation.
detail: Internal.
dictionary: Namespace for carb::dictionary::IDictionary related interfaces and helpers.
eventdispatcher: Namespace for carb.eventdispatcher.plugin and related utilities.
events: Namespace for the carb.events plugin.
extras: Common namespace for extra helper functions and classes.
filesystem: Namespace for Carbonite FileSystem.
input: Namespace for the carb.input plugin.
l10n: Utilities for localizing text.
launcher: Namespace for the Carbonite process launch helper interface.
logging: Namespace for logging interfaces and utilities.
math: Namespace for various math helper functions.
memory
options: Namespace for the options processing helper functions.
process: Namespace for Carbonite process utilities.
profiler: Namespace for carb.profiler and related utilities.
scripting: Namespace for scripting utilities and interfaces.
settings: Namespace for carb::settings::ISettings interface and utilities.
simplegui: Namespace for carb.simplegui plugin.
stats: Namespace for the arbitrary statistics interface.
tasking: Namespace for carb.tasking.plugin and related utilities.
this_process: Namespace for utilities that operate on the current process specifically.
this_thread: Namespace for utilities that operate on the current thread specifically.
thread: Namespace for all threading operations.
time
tokens: Namespace for ITokens .
variant: Namespace for carb.variant.plugin and related utilities.
variant_literals: Namespace for carb.variant literal helpers.
windowing: Namespace for Carbonite Windowing system.

Structs#

AcquireInterfaceOptions: A structure used with Framework::internalAcquireInterface() . Typically callers should use one of the adapter functions such as Framework::tryAcquireInterface() and not use this directly.
Color: RGBA color with templated data type.
ColorRgb: RGB float color.
ColorRgbDouble: RGB double color.
ColorRgba: RGBA float color.
ColorRgbaDouble: RGBA double color.
Double2: Two component double vector.
Double3: Three component double vector.
Double4: Four component double vector.
ErrorApi: The low-level API for interacting with the Carbonite error handling system. At the core, this system maintains a thread-specific error code and optional error message.
FindPluginsArgs: Arguments that are passed to findPlugins() .
Float2: Two component float vector.
Float3: Three component float vector.
Float4: Four component float vector.
Framework: Defines the framework for creating Carbonite applications and plugins.
InitBoth: An empty class tag type used with EmptyMemberPair constructors.
Int2: Two component int32_t vector.
Int3: Three component int32_t vector.
Int4: Four component int32_t vector.
InterfaceDesc: Defines a descriptor for the plugin interface.
PluginDesc: Defines a struct which contains all key information about a plugin loaded into memory.
PluginFrameworkDesc: Pass to each plugin's OnPluginRegisterExFn during load. Allows the plugin to grab global Carbonite state such as the carb::Framework singleton.
PluginImplDesc: Defines a descriptor for the plugin implementation, to be provided to the macro CARB_PLUGIN_IMPL.
PluginLoadingDesc: Describes parameters for finding plugins on disk. Multiple search paths, matching wildcards, and exclusion wildcards can be specified. Used primarily by Framework::loadPlugins .
PluginRegistrationDesc: Describes the different functions a plugin can define for use by carb::Framework .
PluginRegistryEntry: Defines a struct to be filled by a plugin to provide the framework with all information about it.
PluginRegistryEntry2: Defines a struct to be filled by a plugin to provide the framework with all information about it. This struct is automatically created and filled by the macro CARB_PLUGIN_IMPL.
SharedHandle: Defines a shared object handle.
StartupFrameworkDesc: Parameters passed to carb::startupFramework() .
Uint2: Two component uint32_t vector.
Uint3: Three component uint32_t vector.
Uint4: Four component uint32_t vector.
ValueInitFirst: An empty class tag type used with EmptyMemberPair constructors.
Version: Defines a version consisting of a major and minor version.

Typedefs#

AtomicIfTSan: A helper type that is T if TSan is not enabled, or std::atomic<T> if TSan is enabled. Generally used for working around TSan false positives or warnings with complicated (but correct) logic.
FindPluginsOnMatchedFn: Callback that is called when a candidate plugin file is located.
FourCC: A representation that can combine four character codes into a single 32-bit value for quick comparison.
GetFrameworkVersionFn: Required. Returns the plugin's required carb::Framework version.
GetPluginDepsFn: Optional. Returns a static list of interfaces this plugin depends upon.
LoadHookFn: Load Hook function.
LoadHookHandle: A handle type for Framework::addLoadHook() and Framework::removeLoadHook()
OnPluginPostShutdownFn: Optional. Called after OnPluginShutdownFn .
OnPluginPreStartupFn: Optional. Called after OnPluginRegisterExFn .
OnPluginQuickShutdownFn: Optional. Called if provided in lieu of OnPluginShutdownFn when the carb::quickReleaseFrameworkAndTerminate() is performing a quick shutdown.
OnPluginRegisterEx2Fn: Either this or OnPluginRegisterEx2Fn or OnPluginRegisterFn are required. Populates the given carb::PluginRegistryEntry2 with the plugin's information.
OnPluginRegisterExFn: Either this or OnPluginRegisterFn or OnPluginRegisterEx2 are required. Populates the given carb::PluginRegistryEntry with the plugin's information.
OnPluginRegisterFn: Either this or OnPluginRegisterExFn or OnPluginRegisterEx2Fn are required. Populates the given carb::PluginRegistryEntry with the plugin's information.
OnPluginShutdownFn: Optional. Called after OnPluginStartupExFn .
OnPluginStartupExFn: Optional. Called after OnPluginPreStartupFn .
OnPluginStartupFn: Optional. Called after OnPluginPreStartupFn .
OnReloadDependencyFn: Optional.
RegisterHookFn: Register Hook function.
RegisterHookHandle: A handle type for Framework::addRegisterHook() and Framework::removeRegisterHook()
ReleaseHookFn: Release Hook function.
UseCarbAllocator: An object can inherit from this class in order to use Carbonite allocation functions for creation/deletion.

Variables#

constexpr FourCC kCarb_FourCC: Four character code used to identify a PluginRegistrationDesc object that is likely to have further data provided in it.
constexpr uint64_t kFnvBasis: FNV-1a 64-bit hash basis.
constexpr uint64_t kFnvPrime: FNV-1a 64-bit hash prime.
constexpr struct Version kFrameworkVersion: Defines the current version of the Carbonite framework.
constexpr LoadHookHandle kInvalidLoadHook: A value indicating an invalid load hook handle.
constexpr RegisterHookHandle kInvalidRegisterHook: A value indicating an invalid register hook handle.
constexpr uint32_t kTimeoutInfinite: Timeout constant.