Pixar Arch 0.25.8
|
Classes | |
struct | Arch_PerLibInit |
struct | Arch_Unmapper |
struct | ArchBuildMode |
struct | ArchIntervalTimer |
A simple timer class for measuring an interval of time using the ArchTickTimer facilities. More... | |
class | ArchMallocHook |
Override default malloc() functionality. More... | |
class | ArchRegex |
Typedefs | |
typedef struct stat | ArchStatType |
using | ArchConstFileMapping = std::unique_ptr<char const, Arch_Unmapper> |
ArchConstFileMapping and ArchMutableFileMapping are std::unique_ptr<char const *, ...> and std::unique_ptr<char *, ...> respectively. | |
using | ArchMutableFileMapping = std::unique_ptr<char, Arch_Unmapper> |
typedef unsigned char | uchar |
typedef std::function< std::string(uintptr_t address)> | ArchStackTraceCallback |
A callback to get a symbolic representation of an address. | |
typedef void(* | ArchCrashHandlerSystemCB) (void *userData) |
Callback for handling crashes. |
Enumerations | |
enum | ArchMemAdvice { ArchMemAdviceNormal , ArchMemAdviceWillNeed , ArchMemAdviceDontNeed , ArchMemAdviceRandomAccess } |
enum | ArchFileAdvice { ArchFileAdviceNormal , ArchFileAdviceWillNeed , ArchFileAdviceDontNeed , ArchFileAdviceRandomAccess } |
enum | ArchMemoryProtection { ArchProtectNoAccess , ArchProtectReadOnly , ArchProtectReadWrite , ArchProtectReadWriteCopy } |
Memory protection options, see ArchSetMemoryProtection(). More... |
Functions | |
size_t | ArchAlignMemorySize (size_t nBytes) |
Return suitably aligned memory size. | |
void * | ArchAlignMemory (void *base) |
Align memory to the next "best" alignment value. | |
void * | ArchAlignedAlloc (size_t alignment, size_t size) |
Aligned memory allocation. | |
void | ArchAlignedFree (void *ptr) |
Free memory allocated by ArchAlignedAlloc. | |
int | ArchCloseAllFiles (int nExcept, const int *exceptFds) |
Close all file descriptors (with possible exceptions) | |
void | ArchDebuggerTrap () ARCH_NOINLINE |
Stop in a debugger. | |
void | ArchDebuggerWait (bool wait) |
Cause debug traps to wait for the debugger or not. | |
bool | ArchDebuggerAttach () ARCH_NOINLINE |
Attach a debugger. | |
bool | ArchDebuggerIsAttached () ARCH_NOINLINE |
Test if a debugger is attached. | |
void | ArchAbort (bool logging=true) |
Abort. | |
bool | ArchDemangle (std::string *typeName) |
Demangle RTTI-generated type name. | |
std::string | ArchGetDemangled (const std::string &typeName) |
Return demangled RTTI-generated type name. | |
std::string | ArchGetDemangled (const char *typeName) |
Return demangled RTTI-generated type name. | |
std::string | ArchGetDemangled (const std::type_info &typeInfo) |
Return demangled RTTI-generated type name. | |
std::string | ArchGetDemangled (const std::type_index &typeIndex) |
Return demangled RTTI-generated type name. | |
template<typename T> | |
std::string | ArchGetDemangled () |
Return demangled RTTI generated-type name. | |
bool | ArchHasEnv (const std::string &name) |
Architecture dependent access to environment variables. | |
std::string | ArchGetEnv (const std::string &name) |
Gets a value from the current environment identified by name . | |
bool | ArchSetEnv (const std::string &name, const std::string &value, bool overwrite) |
Creates or modifies an environment variable. | |
bool | ArchRemoveEnv (const std::string &name) |
Removes an environment variable. | |
std::string | ArchExpandEnvironmentVariables (const std::string &str) |
Expands environment variables in str . | |
char ** | ArchEnviron () |
Return an array of the environment variables. | |
std::string | ArchStrerror () |
Return the error string for the current value of errno. | |
std::string | ArchStrerror (int errorCode) |
Return the error string for the specified value of errno. | |
FILE * | ArchOpenFile (char const *fileName, char const *mode) |
Opens a file. | |
int | ArchChmod (const char *path, int mode) |
int | ArchCloseFile (int fd) |
int | ArchUnlinkFile (const char *path) |
int | ArchFileAccess (const char *path, int mode) |
FILE * | ArchFdOpen (int fd, const char *mode) |
int | ArchFileNo (FILE *file) |
int | ArchFileIsaTTY (int fd) |
int | ArchRmDir (const char *path) |
int64_t | ArchGetFileLength (const char *fileName) |
Return the length of a file in bytes. | |
int64_t | ArchGetFileLength (FILE *file) |
std::string | ArchGetFileName (FILE *file) |
Return a filename for this file, if one can be obtained. | |
bool | ArchStatIsWritable (const ArchStatType *st) |
Returns true if the data in stat struct st indicates that the target file or directory is writable. | |
bool | ArchGetModificationTime (const char *pathname, double *time) |
Returns the modification time (mtime) in seconds for a file. | |
double | ArchGetModificationTime (const ArchStatType &st) |
Returns the modification time (mtime) in seconds from the stat struct. | |
std::string | ArchNormPath (const std::string &path, bool stripDriveSpecifier=false) |
Normalizes the specified path, eliminating double slashes, etc. | |
std::string | ArchAbsPath (const std::string &path) |
Returns the canonical absolute path of the specified filename. | |
bool | ArchGetStatMode (const char *pathname, int *mode) |
Returns the permissions mode (mode_t) for the given pathname. | |
const char * | ArchGetTmpDir () |
Return the path to a temporary directory for this platform. | |
std::string | ArchMakeTmpFileName (const std::string &prefix, const std::string &suffix=std::string()) |
Make a temporary file name, in a system-determined temporary directory. | |
int | ArchMakeTmpFile (const std::string &prefix, std::string *pathname=0) |
Create a temporary file, in a system-determined temporary directory. | |
int | ArchMakeTmpFile (const std::string &tmpdir, const std::string &prefix, std::string *pathname=0) |
Create a temporary file, in a given temporary directory. | |
std::string | ArchMakeTmpSubdir (const std::string &tmpdir, const std::string &prefix) |
Create a temporary sub-direcrory, in a given temporary directory. | |
size_t | ArchGetFileMappingLength (ArchConstFileMapping const &m) |
Return the length of an ArchConstFileMapping. | |
size_t | ArchGetFileMappingLength (ArchMutableFileMapping const &m) |
Return the length of an ArchMutableFileMapping. | |
ArchConstFileMapping | ArchMapFileReadOnly (FILE *file, std::string *errMsg=nullptr) |
Privately map the passed file into memory and return a unique_ptr to the read-only mapped contents. | |
ArchConstFileMapping | ArchMapFileReadOnly (std::string const &path, std::string *errMsg=nullptr) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
ArchMutableFileMapping | ArchMapFileReadWrite (FILE *file, std::string *errMsg=nullptr) |
Privately map the passed file into memory and return a unique_ptr to the copy-on-write mapped contents. | |
ArchMutableFileMapping | ArchMapFileReadWrite (std::string const &path, std::string *errMsg=nullptr) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
void | ArchMemAdvise (void const *addr, size_t len, ArchMemAdvice adv) |
Advise the OS regarding how the application intends to access a range of memory. | |
bool | ArchQueryMappedMemoryResidency (void const *addr, size_t len, unsigned char *pageMap) |
Report whether or not the mapped virtual memory pages starting at addr for len bytes are resident in RAM. | |
int64_t | ArchPRead (FILE *file, void *buffer, size_t count, int64_t offset) |
Read up to count bytes from offset in file into buffer . | |
int64_t | ArchPWrite (FILE *file, void const *bytes, size_t count, int64_t offset) |
Write up to count bytes from buffer to file at offset . | |
std::string | ArchReadLink (const char *path) |
Returns the value of the symbolic link at path . | |
void | ArchFileAdvise (FILE *file, int64_t offset, size_t count, ArchFileAdvice adv) |
Advise the OS regarding how the application intends to access a range of bytes in a file. | |
std::string | ArchGetPrettierFunctionName (const std::string &function, const std::string &prettyFunction) |
Return well formatted function name. | |
uint32_t | ArchHash (const char *data, size_t len) |
Hash len bytes of data. | |
uint32_t | ArchHash (const char *data, size_t len, uint32_t seed) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
uint64_t | ArchHash64 (const char *data, size_t len) |
Hash len bytes of data. | |
uint64_t | ArchHash64 (const char *data, size_t len, uint64_t seed) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
void * | ArchLibraryOpen (const std::string &filename, int flag) |
library.h Architecture dependent loading and unloading of dynamic libraries. | |
std::string | ArchLibraryError () |
Obtain a description of the most recent error that occurred from ArchLibraryOpen . | |
int | ArchLibraryClose (void *handle) |
Closes an object opened with ArchLibraryOpen . | |
void * | ArchLibraryGetSymbolAddress (void *handle, const char *name) |
Obtain the address of a symbol defined within an object opened with ArchLibraryOpen . | |
bool | ArchIsPtmallocActive () |
Return true if ptmalloc is being used as the memory allocator. | |
bool | ArchIsStlAllocatorOff () |
Return true if the C++ STL allocator was requested to be turned off. | |
long | ArchSign (long val) |
Three-valued sign. Return 1 if val > 0, 0 if val == 0, or -1 if val < 0. | |
uint32_t | ArchFloatToBitPattern (float v) |
Returns The IEEE-754 bit pattern of the specified single precision value as a 32-bit unsigned integer. | |
float | ArchBitPatternToFloat (uint32_t v) |
Returns The single precision floating point value corresponding to the given IEEE-754 bit pattern. | |
uint64_t | ArchDoubleToBitPattern (double v) |
Returns The IEEE-754 bit pattern of the specified double precision value as a 64-bit unsigned integer. | |
double | ArchBitPatternToDouble (uint64_t v) |
Returns The double precision floating point value corresponding to the given IEEE-754 bit pattern. | |
void | ArchSinCosf (float v, float *s, float *c) |
Computes the sine and cosine of the specified value as a float. | |
void | ArchSinCos (double v, double *s, double *c) |
Computes the sine and cosine of the specified value as a double. | |
int | ArchCountTrailingZeros (uint64_t x) |
Return the number of consecutive 0-bits in x starting from the least significant bit position. | |
void | ArchLogFatalProcessState (const char *reason, const char *message=nullptr, const char *extraLogMsg=nullptr) |
Dumps call-stack info to a file, prints a message to the terminal, and invokes crash handling script. | |
void | ArchLogCurrentProcessState (const char *reason, const char *message=nullptr, const char *extraLogMsg=nullptr) |
Dumps call-stack info to a file, and prints an informative message. | |
void | ArchSetProcessStateLogCommand (const char *command, const char *const argv[], const char *const fatalArgv[]) |
Sets command line that gets call-stack info and triggers crash handling script. | |
bool | ArchIsAppCrashing () |
Returns true if the fatal signal handler ArchLogFatalProcessState has been invoked. | |
void | ArchLogSessionInfo (const char *crashStackTrace=NULL) |
Log session info. | |
void | ArchSetLogSession (const char *command, const char *const argv[], const char *const crashArgv[]) |
Sets the command line to log sessions. | |
void | ArchEnableSessionLogging () |
Register the callback to invoke logging at end of a successful session. | |
void | ArchPrintStackTrace (FILE *fout, const std::string &programName, const std::string &reason) |
Print a stack trace to the given FILE pointer. | |
void | ArchPrintStackTrace (FILE *fout, const std::string &reason) |
Print a stack trace to the given FILE pointer. | |
void | ArchPrintStackTrace (std::ostream &out, const std::string &programName, const std::string &reason) |
Print a stack trace to the given ostream. | |
void | ArchPrintStackTrace (std::ostream &out, const std::string &reason) |
Print a stack trace to the given ostream. | |
void | ArchSetStackTraceCallback (const ArchStackTraceCallback &cb) |
Sets a callback to get a symbolic representation of an address. | |
void | ArchGetStackTraceCallback (ArchStackTraceCallback *cb) |
Returns the callback to get a symbolic representation of an address. | |
time_t | ArchGetAppLaunchTime () |
Returns the set value for the application's launch time. | |
void | ArchSetFatalStackLogging (bool flag) |
Enables or disables the automatic logging of crash information. | |
bool | ArchGetFatalStackLogging () |
Returns whether automatic logging of fatal crashes is enabled This is set to false by default. | |
void | ArchSetProgramNameForErrors (const char *progName) |
Sets the program name to be used in diagnostic output. | |
const char * | ArchGetProgramNameForErrors () |
Returns the currently set program name for reporting errors. | |
void | ArchSetProgramInfoForErrors (const std::string &key, const std::string &value) |
Sets additional program info to be reported to the terminal in case of a fatal error. | |
std::string | ArchGetProgramInfoForErrors (const std::string &key) |
Returns currently set program info. | |
void | ArchSetExtraLogInfoForErrors (const std::string &key, std::vector< std::string > const *lines) |
Stores (or removes if lines is nullptr) a pointer to additional log data that will be output in the stack trace log in case of a fatal error. | |
void | ArchLogStackTrace (const std::string &progName, const std::string &reason, bool fatal=false, const std::string &sessionLog="") |
Logs a stack trace to a file in /var/tmp. | |
void | ArchLogStackTrace (const std::string &reason, bool fatal=false, const std::string &sessionLog="") |
Logs a stack trace to a file in /var/tmp. | |
std::vector< std::string > | ArchGetStackTrace (size_t maxDepth) |
Return stack trace. | |
void | ArchGetStackFrames (size_t maxDepth, std::vector< uintptr_t > *frames) |
Save frames of current stack. | |
size_t | ArchGetStackFrames (size_t maxDepth, uintptr_t *frames) |
Store at most maxDepth frames of the current stack into frames . | |
void | ArchGetStackFrames (size_t maxDepth, size_t numFramesToSkipAtTop, std::vector< uintptr_t > *frames) |
Save frames of current stack. | |
size_t | ArchGetStackFrames (size_t maxDepth, size_t numFramesToSkipAtTop, uintptr_t *frames) |
Store at most maxDepth frames of the current stack into frames , skipping the first numFramesToSkipAtTop frames. | |
void | ArchPrintStackFrames (std::ostream &out, const std::vector< uintptr_t > &frames, bool skipUnknownFrames=false) |
Print stack frames to the given ostream. | |
int | ArchCrashHandlerSystemv (const char *pathname, char *const argv[], int timeout, ArchCrashHandlerSystemCB callback, void *userData) |
Replacement for 'system' safe for a crash handler. | |
bool | ArchGetAddressInfo (void *address, std::string *objectPath, void **baseAddress, std::string *symbolName, void **symbolAddress) |
Returns information about the address address in the running program. | |
std::string | ArchGetCwd () |
Return current working directory as a string. | |
std::string | ArchGetExecutablePath () |
Return the path to the program's executable. | |
int | ArchGetPageSize () |
Return the system's memory page size. Safe to assume power-of-two. | |
bool | ArchIsMainThread () |
Return true if the calling thread is the main thread, false otherwise. | |
std::thread::id | ArchGetMainThreadId () |
Return the std::thread_id for the thread arch considers to be the "main" thread. | |
uint64_t | ArchGetTickTime () |
Return the current time in system-dependent units. | |
uint64_t | ArchGetStartTickTime () |
Get a "start" tick time for measuring an interval of time, followed by a later call to ArchGetStopTickTime(). | |
uint64_t | ArchGetStopTickTime () |
Get a "stop" tick time for measuring an interval of time. | |
uint64_t | ArchGetTickQuantum () |
Return the tick time resolution. | |
uint64_t | ArchGetIntervalTimerTickOverhead () |
Return the ticks taken to record an interval of time with ArchIntervalTimer, as measured at startup time. | |
int64_t | ArchTicksToNanoseconds (uint64_t nTicks) |
Convert a duration measured in "ticks", as returned by ArchGetTickTime() , to nanoseconds. | |
double | ArchTicksToSeconds (uint64_t nTicks) |
Convert a duration measured in "ticks", as returned by ArchGetTickTime() , to seconds. | |
uint64_t | ArchSecondsToTicks (double seconds) |
Convert a duration in seconds to "ticks", as returned by ArchGetTickTime() . | |
double | ArchGetNanosecondsPerTick () |
Get nanoseconds per tick. | |
uint64_t | Arch_MeasureExecutionTime (uint64_t maxTicks, bool *reachedConsensus, void const *m, uint64_t(*callM)(void const *, int)) |
template<class Fn> | |
uint64_t | ArchMeasureExecutionTime (Fn const &fn, uint64_t maxTicks=1e7, bool *reachedConsensus=nullptr) |
Run fn repeatedly attempting to determine a consensus fastest execution time with low noise, for up to maxTicks , then return the consensus fastest execution time. | |
void * | ArchReserveVirtualMemory (size_t numBytes) |
Reserve numBytes bytes of virtual memory. | |
bool | ArchCommitVirtualMemoryRange (void *start, size_t numBytes) |
Make the range of numBytes bytes starting at start available for reading and writing. | |
bool | ArchFreeVirtualMemory (void *start, size_t numBytes) |
Return memory obtained with ArchReserveVirtualMemory() to the system. | |
bool | ArchSetMemoryProtection (void const *start, size_t numBytes, ArchMemoryProtection protection) |
Change the memory protection on the pages containing start and start + numBytes to protection . | |
int | ArchVsnprintf (char *str, size_t size, const char *format, va_list ap) |
Return the number of characters (not including the null character) necessary for a particular sprintf into a string. | |
std::string | ArchStringPrintf (const char *fmt,...) |
Returns a string formed by a printf()-like specification. | |
std::string | ArchVStringPrintf (const char *fmt, va_list ap) |
Returns a string formed by a printf()-like specification. |
Variables | |
template<class StaticInit> | |
StaticInit | Arch_PerLibInit< StaticInit >::init |
Scope of Pixar’s public API.
typedef struct stat pxr::ArchStatType |
using pxr::ArchConstFileMapping = std::unique_ptr<char const, Arch_Unmapper> |
ArchConstFileMapping and ArchMutableFileMapping are std::unique_ptr<char const *, ...> and std::unique_ptr<char *, ...> respectively.
The functions ArchMapFileReadOnly() and ArchMapFileReadWrite() return them and provide access to memory-mapped file contents.
using pxr::ArchMutableFileMapping = std::unique_ptr<char, Arch_Unmapper> |
typedef unsigned char pxr::uchar |
typedef std::function<std::string(uintptr_t address)> pxr::ArchStackTraceCallback |
A callback to get a symbolic representation of an address.
typedef void(* pxr::ArchCrashHandlerSystemCB) (void *userData) |
Callback for handling crashes.
enum pxr::ArchMemAdvice |
enum pxr::ArchFileAdvice |
Memory protection options, see ArchSetMemoryProtection().
Enumerator | |
---|---|
ArchProtectNoAccess | |
ArchProtectReadOnly | |
ArchProtectReadWrite | |
ArchProtectReadWriteCopy |
|
inline |
Return suitably aligned memory size.
Requests to malloc()
or ::new
for a given size are often rounded upward. Given a request for nBytes
bytes of storage, this function returns the amount that would actually be consumed by the system to satisfy it. This is needed for efficient user-defined memory management.
|
inline |
Align memory to the next "best" alignment value.
This will take a pointer and bump it to the next ideal alignment boundary that will work for all data types.
void * pxr::ArchAlignedAlloc | ( | size_t | alignment, |
size_t | size ) |
Aligned memory allocation.
void pxr::ArchAlignedFree | ( | void * | ptr | ) |
Free memory allocated by ArchAlignedAlloc.
int pxr::ArchCloseAllFiles | ( | int | nExcept, |
const int * | exceptFds ) |
Close all file descriptors (with possible exceptions)
ArchCloseAllFiles
will close all file descriptors open in the current process. Occasionally you'd like to close all files except for some small subset (like 0, 1, and 2). The nExcept
and exceptFds
arguments can be used to provide the list of exceptions. ArchDaemonizeProcess
uses this method to close all unwanted file descriptors in the daemon process.
nExcept
should be the number of elements in the exceptFds
array. Invalid file descriptors in exceptFds are ignored.
fork(2)
call to close all unwanted file descriptors. However, it does not flush stdio buffers, wait for processes opened with popen, shut down the X11 display connection, or anything. It just slams closed all the file descriptors. This is appropriate following a fork(2)
call as all these file descriptors are duplicates of the ones in the parent process and shutting down the X11 display connection would mess up the parent's X11 display. But you shouldn't use ArchCloseAllFiles
unless you know what you are doing.errno
will be set to an appropriate value. Returns 0 on success. void pxr::ArchDebuggerTrap | ( | ) |
Stop in a debugger.
This function will do one of the following: start a debugger attached to this process stopped on this function; stop in an already attached debugger; stop and wait for a debugger to attach, or nothing.
On Linux this will start a debugger using ArchDebuggerAttach()
if no debugger is attached. If a debugger is (or was) attached it will stop on this function due to SIGTRAP
. Alternatively, users can configure the debugger to not stop on SIGTRAP
and instead break on ArchDebuggerTrap()
.
If a debugger is not attached, ArchDebuggerAttach()
does not attach one, and ArchDebuggerWait()
has been most recently called with true
then this will wait for a debugger to attach, otherwise it does nothing and the process does not stop. The user can continue the process from the debugger simply by issuing the continue command. The user can also continue the process from an attached terminal by putting the process into the foreground or background.
void pxr::ArchDebuggerWait | ( | bool | wait | ) |
Cause debug traps to wait for the debugger or not.
When wait
is true
the next call to ArchDebuggerTrap()
will cause the process to wait for a signal. The user can attach a debugger to continue the process. The process will not wait again until another call to this function with wait
true
.
bool pxr::ArchDebuggerAttach | ( | ) |
Attach a debugger.
Attaches the debugger by running the contents of the enviroment variable ARCH_DEBUGGER using /bin/sh. Any 'p' in the contents of this variable will be replaced with the process id of the process launching the debugger. Any 'e' will be replaced with the path to the executable for the process.
Returns true if ARCH_DEBUGGER is set and the debugger was successfully launched, otherwise returns false.
bool pxr::ArchDebuggerIsAttached | ( | ) |
Test if a debugger is attached.
Attempts to detect if a debugger is currently attached to the process.
void pxr::ArchAbort | ( | bool | logging = true | ) |
Abort.
This will try to avoid the JIT debugger if any if ARCH_AVOID_JIT is in the environment and the debugger isn't already attached. In that case it will _exit(134). If logging
is false
then this will attempt to bypass any crash logging.
bool pxr::ArchDemangle | ( | std::string * | typeName | ) |
Demangle RTTI-generated type name.
Given a variable v
, the construct typeid(v)
.name() returns the type-name of v
; unfortunately, the returned type-name is sometimes extremely encoded (otherwise known as "mangled"). ArchDemangle
parses the passed in type-name typeName
into a readable form, and overwrites typeName
. If typeName
cannot be unmangled, the function returns false
without altering typeName
. Otherwise true
is returned.
std::string pxr::ArchGetDemangled | ( | const std::string & | typeName | ) |
Return demangled RTTI-generated type name.
If typeName
can be demangled, the function returns the demangled string; otherwise, the function returns the empty string.
std::string pxr::ArchGetDemangled | ( | const char * | typeName | ) |
Return demangled RTTI-generated type name.
|
inline |
Return demangled RTTI-generated type name.
Returns the demangled name associated with typeInfo (i.e. typeInfo.name()).
|
inline |
Return demangled RTTI-generated type name.
Returns the demangled name associated with typeIndex (i.e. typeIndex.name()).
|
inline |
Return demangled RTTI generated-type name.
Returns the demangled name of type T.
bool pxr::ArchHasEnv | ( | const std::string & | name | ) |
Architecture dependent access to environment variables.
Returns true
if and only if the current environment contains name
.
std::string pxr::ArchGetEnv | ( | const std::string & | name | ) |
Gets a value from the current environment identified by name
.
bool pxr::ArchSetEnv | ( | const std::string & | name, |
const std::string & | value, | ||
bool | overwrite ) |
Creates or modifies an environment variable.
bool pxr::ArchRemoveEnv | ( | const std::string & | name | ) |
Removes an environment variable.
std::string pxr::ArchExpandEnvironmentVariables | ( | const std::string & | str | ) |
Expands environment variables in str
.
char ** pxr::ArchEnviron | ( | ) |
Return an array of the environment variables.
std::string pxr::ArchStrerror | ( | ) |
Return the error string for the current value of errno.
This function provides a thread-safe method of fetching the error string from errno. POSIX.1c defines errno as a macro which provides access to a thread-local integer. This function is thread-safe. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
std::string pxr::ArchStrerror | ( | int | errorCode | ) |
Return the error string for the specified value of errno.
This function is thread-safe.
FILE * pxr::ArchOpenFile | ( | char const * | fileName, |
char const * | mode ) |
Opens a file.
Opens the file that is specified by filename. Returning true if the file was opened successfully; false otherwise.
int pxr::ArchChmod | ( | const char * | path, |
int | mode ) |
int pxr::ArchCloseFile | ( | int | fd | ) |
int pxr::ArchUnlinkFile | ( | const char * | path | ) |
int pxr::ArchFileAccess | ( | const char * | path, |
int | mode ) |
FILE * pxr::ArchFdOpen | ( | int | fd, |
const char * | mode ) |
int pxr::ArchFileNo | ( | FILE * | file | ) |
int pxr::ArchFileIsaTTY | ( | int | fd | ) |
int pxr::ArchRmDir | ( | const char * | path | ) |
int64_t pxr::ArchGetFileLength | ( | const char * | fileName | ) |
Return the length of a file in bytes.
Returns -1 if the file cannot be opened/read.
int64_t pxr::ArchGetFileLength | ( | FILE * | file | ) |
std::string pxr::ArchGetFileName | ( | FILE * | file | ) |
Return a filename for this file, if one can be obtained.
Note that there are many reasons why it may be impossible to obtain a filename, even for an opened FILE *. Whenever possible avoid using this function and instead store the filename for future use.
bool pxr::ArchStatIsWritable | ( | const ArchStatType * | st | ) |
Returns true if the data in stat
struct st
indicates that the target file or directory is writable.
This returns true if the struct pointer is valid, and the stat indicates the target is writable by the effective user, effective group, or all users.
bool pxr::ArchGetModificationTime | ( | const char * | pathname, |
double * | time ) |
Returns the modification time (mtime) in seconds for a file.
This function stores the modification time with as much precision as is available in the stat structure for the current platform in time
and returns true
on success, otherwise just returns false
.
double pxr::ArchGetModificationTime | ( | const ArchStatType & | st | ) |
Returns the modification time (mtime) in seconds from the stat struct.
This function returns the modification time with as much precision as is available in the stat structure for the current platform.
std::string pxr::ArchNormPath | ( | const std::string & | path, |
bool | stripDriveSpecifier = false ) |
Normalizes the specified path, eliminating double slashes, etc.
This canonicalizes paths, removing any double slashes, and eliminiating '.', and '..' components of the path. This emulates the behavior of os.path.normpath in Python.
On Windows, all backslashes are converted to forward slashes and drive specifiers (e.g., "C:") are lower-cased. If stripDriveSpecifier
is true
, these drive specifiers are removed from the path.
std::string pxr::ArchAbsPath | ( | const std::string & | path | ) |
Returns the canonical absolute path of the specified filename.
This makes the specified path absolute, by prepending the current working directory. If the path is already absolute, it is returned unmodified.
bool pxr::ArchGetStatMode | ( | const char * | pathname, |
int * | mode ) |
Returns the permissions mode (mode_t) for the given pathname.
This function stats the given pathname and returns the permissions flags for it and returns true. If the stat fails, returns false.
const char * pxr::ArchGetTmpDir | ( | ) |
Return the path to a temporary directory for this platform.
The returned temporary directory will be a location that will normally be cleaned out on a reboot. This is /var/tmp on Linux machines (for legacy reasons), but /tmp on Darwin machines (/var/tmp on Darwin is specified as a location where files are kept between system reboots - see "man hier"). The returned string will not have a trailing slash.
This routine is threadsafe and will not perform any memory allocations.
std::string pxr::ArchMakeTmpFileName | ( | const std::string & | prefix, |
const std::string & | suffix = std::string() ) |
Make a temporary file name, in a system-determined temporary directory.
The result returned has the form TMPDIR/prefix.pid[.n]suffix where TMPDIR is a system-determined temporary directory (typically /tmp or /usr/tmp), pid is the process id of the process, and the optional .n records the number of times this function has been called by a process (and is ommited the first time this function is called).
The call is threadsafe.
ArchMakeTmpFile()
. int pxr::ArchMakeTmpFile | ( | const std::string & | prefix, |
std::string * | pathname = 0 ) |
Create a temporary file, in a system-determined temporary directory.
The result returned has the form TMPDIR/prefix.XXXXXX where TMPDIR is a system-determined temporary directory (typically /tmp or /usr/tmp) and XXXXXX is a unique suffix. Returns the file descriptor of the new file and, if pathname isn't NULL, returns the full path to the file in pathname. Returns -1 on failure and errno is set.
The call is threadsafe.
int pxr::ArchMakeTmpFile | ( | const std::string & | tmpdir, |
const std::string & | prefix, | ||
std::string * | pathname = 0 ) |
Create a temporary file, in a given temporary directory.
The result returned has the form TMPDIR/prefix.XXXXXX where TMPDIR is the given temporary directory and XXXXXX is a unique suffix. Returns the file descriptor of the new file and, if pathname isn't NULL, returns the full path to the file in pathname. Returns -1 on failure and errno is set.
The call is threadsafe.
std::string pxr::ArchMakeTmpSubdir | ( | const std::string & | tmpdir, |
const std::string & | prefix ) |
Create a temporary sub-direcrory, in a given temporary directory.
The result returned has the form TMPDIR/prefix.XXXXXX/ where TMPDIR is the given temporary directory and XXXXXX is a unique suffix. Returns the the full path to the subdir in pathname. Returns empty string on failure and errno is set.
The call is threadsafe.
|
inline |
Return the length of an ArchConstFileMapping.
|
inline |
Return the length of an ArchMutableFileMapping.
ArchConstFileMapping pxr::ArchMapFileReadOnly | ( | FILE * | file, |
std::string * | errMsg = nullptr ) |
Privately map the passed file
into memory and return a unique_ptr to the read-only mapped contents.
The contents may not be modified. If mapping fails, return a null unique_ptr and if errMsg is not null fill it with information about the failure.
ArchConstFileMapping pxr::ArchMapFileReadOnly | ( | std::string const & | path, |
std::string * | errMsg = nullptr ) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
ArchMutableFileMapping pxr::ArchMapFileReadWrite | ( | FILE * | file, |
std::string * | errMsg = nullptr ) |
Privately map the passed file
into memory and return a unique_ptr to the copy-on-write mapped contents.
If modified, the affected pages are dissociated from the underlying file and become backed by the system's swap or page-file storage. Edits are not carried through to the underlying file. If mapping fails, return a null unique_ptr and if errMsg is not null fill it with information about the failure.
ArchMutableFileMapping pxr::ArchMapFileReadWrite | ( | std::string const & | path, |
std::string * | errMsg = nullptr ) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void pxr::ArchMemAdvise | ( | void const * | addr, |
size_t | len, | ||
ArchMemAdvice | adv ) |
Advise the OS regarding how the application intends to access a range of memory.
See ArchMemAdvice. This is primarily useful for mapped file regions. This call does not change program semantics. It is only an optimization hint to the OS, and may be a no-op on some systems.
bool pxr::ArchQueryMappedMemoryResidency | ( | void const * | addr, |
size_t | len, | ||
unsigned char * | pageMap ) |
Report whether or not the mapped virtual memory pages starting at addr
for len
bytes are resident in RAM.
Pages that are resident will not, when accessed, cause a page fault while those that are not will. Return true on success and false in case of an error. The addr
argument must be a multiple of ArchGetPageSize(). The len
argument need not be a multiple of the page size; it will be rounded up to the next page boundary. Fill pageMap
with 0s for pages not resident in memory and 1s for pages that are. The pageMap
argument must therefore point to at least (len
+ ArchGetPageSize()-1)/ArchGetPageSize() bytes.
Note that currently this function is only implemented on Linux and Darwin. On Windows it currently always returns false.
int64_t pxr::ArchPRead | ( | FILE * | file, |
void * | buffer, | ||
size_t | count, | ||
int64_t | offset ) |
Read up to count
bytes from offset
in file
into buffer
.
The file position indicator for file
is not changed. Return the number of bytes read, or zero if at end of file. Return -1 in case of an error, with errno set appropriately.
int64_t pxr::ArchPWrite | ( | FILE * | file, |
void const * | bytes, | ||
size_t | count, | ||
int64_t | offset ) |
Write up to count
bytes from buffer
to file
at offset
.
The file position indicator for file
is not changed. Return the number of bytes written, possibly zero if none written. Return -1 in case of an error, with errno set appropriately.
std::string pxr::ArchReadLink | ( | const char * | path | ) |
Returns the value of the symbolic link at path
.
Returns the empty string on error or if path
does not refer to a symbolic link.
void pxr::ArchFileAdvise | ( | FILE * | file, |
int64_t | offset, | ||
size_t | count, | ||
ArchFileAdvice | adv ) |
Advise the OS regarding how the application intends to access a range of bytes in a file.
See ArchFileAdvice. This call does not change program semantics. It is only an optimization hint to the OS, and may be a no-op on some systems.
std::string pxr::ArchGetPrettierFunctionName | ( | const std::string & | function, |
const std::string & | prettyFunction ) |
Return well formatted function name.
This function assumes function
is ARCH_FUNCTION and prettyFunction
is ARCH_PRETTY_FUNCTION, and attempts to reconstruct a well formatted function name.
uint32_t pxr::ArchHash | ( | const char * | data, |
size_t | len ) |
Hash len bytes of data.
To compute a hash value for data that is not contiguous in memory, iterate over all the contiguous blocks of memory and accumulate the hash value by passing it on as seed
. Note that this is not equivalent to hashing the contiguous pieces as a whole. Support for that may be added in future.
uint32_t pxr::ArchHash | ( | const char * | data, |
size_t | len, | ||
uint32_t | seed ) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
uint64_t pxr::ArchHash64 | ( | const char * | data, |
size_t | len ) |
Hash len bytes of data.
To compute a hash value for data that is not contiguous in memory, iterate over all the contiguous blocks of memory and accumulate the hash value by passing it on as seed
. Note that this is not equivalent to hashing the contiguous pieces as a whole. Support for that may be added in future.
uint64_t pxr::ArchHash64 | ( | const char * | data, |
size_t | len, | ||
uint64_t | seed ) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void * pxr::ArchLibraryOpen | ( | const std::string & | filename, |
int | flag ) |
library.h Architecture dependent loading and unloading of dynamic libraries.
Load an executable object file.
Opens the dynamic library that is specified by filename. Returning the handle to the module if successful; false otherwise.
std::string pxr::ArchLibraryError | ( | ) |
Obtain a description of the most recent error that occurred from ArchLibraryOpen
.
int pxr::ArchLibraryClose | ( | void * | handle | ) |
Closes an object opened with ArchLibraryOpen
.
void * pxr::ArchLibraryGetSymbolAddress | ( | void * | handle, |
const char * | name ) |
Obtain the address of a symbol defined within an object opened with ArchLibraryOpen
.
Obtain the address of a symbol that is specified by name. Returning the address of the symbol if successful; nullptr otherwise.
bool pxr::ArchIsPtmallocActive | ( | ) |
Return true if ptmalloc is being used as the memory allocator.
ptmalloc3 is an external shared library providing implementations of the standard memory allocation functions (e.g. malloc, free). Consumers with special behavior that depends on this library may use this function to determine if it is the active allocator.
bool pxr::ArchIsStlAllocatorOff | ( | ) |
Return true if the C++ STL allocator was requested to be turned off.
Under gcc, this is done by setting the environment variable GLIBCXX_FORCE_NEW, but it might differ (or not even be possible) for other platforms.
|
inline |
Three-valued sign. Return 1 if val > 0, 0 if val == 0, or -1 if val < 0.
|
inline |
Returns The IEEE-754 bit pattern of the specified single precision value as a 32-bit unsigned integer.
|
inline |
Returns The single precision floating point value corresponding to the given IEEE-754 bit pattern.
|
inline |
Returns The IEEE-754 bit pattern of the specified double precision value as a 64-bit unsigned integer.
|
inline |
Returns The double precision floating point value corresponding to the given IEEE-754 bit pattern.
|
inline |
Computes the sine and cosine of the specified value as a float.
|
inline |
Computes the sine and cosine of the specified value as a double.
|
inline |
Return the number of consecutive 0-bits in x
starting from the least significant bit position.
If x
is 0, the result is undefined.
void pxr::ArchLogFatalProcessState | ( | const char * | reason, |
const char * | message = nullptr, | ||
const char * | extraLogMsg = nullptr ) |
Dumps call-stack info to a file, prints a message to the terminal, and invokes crash handling script.
The reason for the trace should be supplied in reason
. An additional message may be provided in message
. If reason
is NULL
then this function only writes message
to the banner (if any).
This routine can be slow and is intended to be called for a fatal error, such as a caught coredump signal. While it can theoretically be called at any time, ArchLogCurrentProcessState()
should be used for nonfatal cases.
This function is implemented by calling an external program. This is suitable for times where the current process may be corrupted. In other cases, using ArchPrintStackTrace()
or other related functions would be much faster.
Note the use of char*
as opposed to string:
this is intentional, because we are trying to use only async-safe function from here on and malloc() is not async-safe.
void pxr::ArchLogCurrentProcessState | ( | const char * | reason, |
const char * | message = nullptr, | ||
const char * | extraLogMsg = nullptr ) |
Dumps call-stack info to a file, and prints an informative message.
The reason for the trace should be supplied in reason
. An additional message may be provided in message
. If reason
is NULL
then this function only writes message
to the banner (if any).
This function is nearly identical to ArchLogFatalProcessState, including calling an external program. However, it is intended for cases that may simulate or require the output info from a full fatal crash, but are not truly fatal errors. For cases where that is not necessary, using ArchPrintStackTrace()
or other related functions would be much faster.
Note the use of char*
as opposed to string:
this is intentional, because we are trying to use only async-safe function from here on and malloc() is not async-safe.
void pxr::ArchSetProcessStateLogCommand | ( | const char * | command, |
const char *const | argv[], | ||
const char *const | fatalArgv[] ) |
Sets command line that gets call-stack info and triggers crash handling script.
This function sets the command line to execute to gather and log call-stack info. argv
must be NULL terminated. If command
and/or argv
(or fatalArgv
in the case of a fatal crash) are NULL, then the command will not be executed. Otherwise argv[0] and fatalArgv[0] must be the full path to the program to execute, typically command
or "$cmd" as described below.
command
, argv
, and fatalArgv
are not copied and must remain valid until the next call to ArchSetProcessStateLogCommand
.
Simple substitution is supported on argv elements:
bool pxr::ArchIsAppCrashing | ( | ) |
Returns true if the fatal signal handler ArchLogFatalProcessState has been invoked.
void pxr::ArchLogSessionInfo | ( | const char * | crashStackTrace = NULL | ) |
Log session info.
Optionally indicate that this is due to a crash by providing the path to a file containing a stack trace in crashStackTrace
.
void pxr::ArchSetLogSession | ( | const char * | command, |
const char *const | argv[], | ||
const char *const | crashArgv[] ) |
Sets the command line to log sessions.
This function sets the command line to execute to log session info. argv
is used if no crash stack trace is provided, otherwise crashArgv
is used. Both must be NULL terminated. If command
or argv
is NULL then non-crashes are not logged; if command
or crashArgv
is NULL then crashes are not logged. If not NULL then argv[0] and crashArgv[0] must be full path to the program to execute, typically command
or "$cmd" as described below.
command
, argv
, and crashArgv
are not copied and must remain valid until the next call to ArchSetLogSession
.
Simple substitution is supported on argv elements:
void pxr::ArchEnableSessionLogging | ( | ) |
Register the callback to invoke logging at end of a successful session.
This function registers ArchLogSessionInfo() and records the current timestamp, to send up-time to the DB upon exiting.
void pxr::ArchPrintStackTrace | ( | FILE * | fout, |
const std::string & | programName, | ||
const std::string & | reason ) |
Print a stack trace to the given FILE pointer.
void pxr::ArchPrintStackTrace | ( | FILE * | fout, |
const std::string & | reason ) |
Print a stack trace to the given FILE pointer.
This function uses ArchGetProgramInfoForErrors as the programName
. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void pxr::ArchPrintStackTrace | ( | std::ostream & | out, |
const std::string & | programName, | ||
const std::string & | reason ) |
Print a stack trace to the given ostream.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void pxr::ArchPrintStackTrace | ( | std::ostream & | out, |
const std::string & | reason ) |
Print a stack trace to the given ostream.
This function uses ArchGetProgramInfoForErrors as the programName
. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void pxr::ArchSetStackTraceCallback | ( | const ArchStackTraceCallback & | cb | ) |
Sets a callback to get a symbolic representation of an address.
The callback returns a string for an address in a stack trace, typically including the name of the function containing the address. cb
may be NULL
to use a default implementation.
void pxr::ArchGetStackTraceCallback | ( | ArchStackTraceCallback * | cb | ) |
Returns the callback to get a symbolic representation of an address.
time_t pxr::ArchGetAppLaunchTime | ( | ) |
Returns the set value for the application's launch time.
The timestamp for this value is set when the arch library is initialized.
void pxr::ArchSetFatalStackLogging | ( | bool | flag | ) |
Enables or disables the automatic logging of crash information.
This function controls whether the stack trace and build information is automatically caught and stored to an internal database when a fatal crash occurs.
bool pxr::ArchGetFatalStackLogging | ( | ) |
Returns whether automatic logging of fatal crashes is enabled This is set to false by default.
void pxr::ArchSetProgramNameForErrors | ( | const char * | progName | ) |
Sets the program name to be used in diagnostic output.
The default value is initialized to ArchGetExecutablePath().
const char * pxr::ArchGetProgramNameForErrors | ( | ) |
Returns the currently set program name for reporting errors.
Defaults to ArchGetExecutablePath().
void pxr::ArchSetProgramInfoForErrors | ( | const std::string & | key, |
const std::string & | value ) |
Sets additional program info to be reported to the terminal in case of a fatal error.
std::string pxr::ArchGetProgramInfoForErrors | ( | const std::string & | key | ) |
Returns currently set program info.
void pxr::ArchSetExtraLogInfoForErrors | ( | const std::string & | key, |
std::vector< std::string > const * | lines ) |
Stores (or removes if lines
is nullptr) a pointer to additional log data that will be output in the stack trace log in case of a fatal error.
Note that the pointer lines
is copied, not the pointed-to data. In addition, Arch might read the data pointed to by lines
concurrently at any time. Thus it is the caller's responsibility to ensure that lines
is both valid and not mutated until replacing or removing it by invoking this function again with the same key
and different lines
.
void pxr::ArchLogStackTrace | ( | const std::string & | progName, |
const std::string & | reason, | ||
bool | fatal = false, | ||
const std::string & | sessionLog = "" ) |
Logs a stack trace to a file in /var/tmp.
This function is similar to ArchLogPostMortem()
, but will not fork an external process and only reports a stack trace. A file in /var/tmp is created with the name st_APPNAME.XXXXXX
, where mktemp
is used to make a unique extension for the file. If sessionLog
is specified, then it will be appended to this file. A message is printed to stderr
reporting that a stack trace has been taken and what file it has been written to. And if fatal
is true, then the stack trace will be added to the stack_trace database table.
void pxr::ArchLogStackTrace | ( | const std::string & | reason, |
bool | fatal = false, | ||
const std::string & | sessionLog = "" ) |
Logs a stack trace to a file in /var/tmp.
This function is similar to ArchLogPostMortem()
, but will not fork an external process and only reports a stack trace. A file in /var/tmp is created with the name st_APPNAME.XXXXXX
, where mktemp
is used to make a unique extension for the file. If sessionLog
is specified, then it will be appended to this file. A message is printed to stderr
reporting that a stack trace has been taken and what file it has been written to. And if fatal
is true, then the stack trace will be added to the stack_trace database table.
std::vector< std::string > pxr::ArchGetStackTrace | ( | size_t | maxDepth | ) |
Return stack trace.
This function will return a vector of strings containing the current stack. The vector will be of maximum size maxDepth
.
void pxr::ArchGetStackFrames | ( | size_t | maxDepth, |
std::vector< uintptr_t > * | frames ) |
Save frames of current stack.
This function saves at maximum maxDepth
frames of the current stack into the vector frames
.
size_t pxr::ArchGetStackFrames | ( | size_t | maxDepth, |
uintptr_t * | frames ) |
Store at most maxDepth
frames of the current stack into frames
.
Return the number of stack frames written to frames
.
void pxr::ArchGetStackFrames | ( | size_t | maxDepth, |
size_t | numFramesToSkipAtTop, | ||
std::vector< uintptr_t > * | frames ) |
Save frames of current stack.
This function saves at maximum maxDepth
frames of the current stack into the vector frames
, skipping the first numFramesToSkipAtTop
frames. The first frame will be at depth numFramesToSkipAtTop
and the last at depth numFramesToSkipAtTop
+ maxDepth
- 1.
size_t pxr::ArchGetStackFrames | ( | size_t | maxDepth, |
size_t | numFramesToSkipAtTop, | ||
uintptr_t * | frames ) |
Store at most maxDepth
frames of the current stack into frames
, skipping the first numFramesToSkipAtTop
frames.
Return the number of stack frames written to frames
.
void pxr::ArchPrintStackFrames | ( | std::ostream & | out, |
const std::vector< uintptr_t > & | frames, | ||
bool | skipUnknownFrames = false ) |
Print stack frames to the given ostream.
int pxr::ArchCrashHandlerSystemv | ( | const char * | pathname, |
char *const | argv[], | ||
int | timeout, | ||
ArchCrashHandlerSystemCB | callback, | ||
void * | userData ) |
Replacement for 'system' safe for a crash handler.
This function is a substitute for system() which does not allocate or free any data, and times out after timeout
seconds if the operation in argv
is not complete. Unlike system, it takes the full pathname
of the program to run, and won't search the path. Also unlike system, argv
[] are the separated arguments, starting with the program's name, as for execv. callback
is called every second. userData
is passed to callback
. callback
can be used, for example, to print a '.' repeatedly to show progress. The alarm used in this function could interfere with setitimer or other calls to alarm, and this function uses non-locking fork and exec if available so should not generally be used except following a catastrophe.
bool pxr::ArchGetAddressInfo | ( | void * | address, |
std::string * | objectPath, | ||
void ** | baseAddress, | ||
std::string * | symbolName, | ||
void ** | symbolAddress ) |
Returns information about the address address
in the running program.
Returns false
if no information can be found, otherwise returns true
and modifies the other arguments: objectPath
is set to the absolute path to the executable or library the address is found in, baseAddress
is the address where that object is loaded, symbolName
is the symbolic name of the thing containing the address, and symbolAddress
is the starting address of that thing. If no thing is found to contain the address then symbolName
is cleared and symbolAddress
is set to NULL
. Any of the arguments except address
can be NULL
if the result isn't needed. This will return false
if NULL
is passed to address
.
std::string pxr::ArchGetCwd | ( | ) |
Return current working directory as a string.
std::string pxr::ArchGetExecutablePath | ( | ) |
Return the path to the program's executable.
int pxr::ArchGetPageSize | ( | ) |
Return the system's memory page size. Safe to assume power-of-two.
bool pxr::ArchIsMainThread | ( | ) |
Return true if the calling thread is the main thread, false otherwise.
std::thread::id pxr::ArchGetMainThreadId | ( | ) |
Return the std::thread_id for the thread arch considers to be the "main" thread.
|
inline |
Return the current time in system-dependent units.
The current time is returned as a number of "ticks", where each tick represents some system-dependent amount of time. The resolution of the timing routines varies, but on all systems, it is well under one microsecond. The cost of this routine is in the 10s-to-100s of nanoseconds on GHz class machines.
|
inline |
Get a "start" tick time for measuring an interval of time, followed by a later call to ArchGetStopTickTime().
Or see ArchIntervalTimer. This is like ArchGetTickTime but it includes compiler & CPU fencing & reordering constraints in an attempt to get the best measurement possible.
|
inline |
Get a "stop" tick time for measuring an interval of time.
See ArchGetStartTickTime() or ArchIntervalTimer. This is like ArchGetTickTime but it includes compiler & CPU fencing & reordering constraints in an attempt to get the best measurement possible.
uint64_t pxr::ArchGetTickQuantum | ( | ) |
Return the tick time resolution.
Although the number of ticks per second may be very large, on many current systems the tick timers do not update at that rate. Rather, sequential calls to ArchGetTickTime() may report increases of 10s to 100s of ticks, with a minimum increment betwewen calls. This function returns that minimum increment as measured at startup time.
Note that if this value is of sufficient size, then short times measured with tick timers are potentially subject to significant noise. In particular, an interval of measured tick time is liable to be off by +/- one ArchGetTickQuantum().
uint64_t pxr::ArchGetIntervalTimerTickOverhead | ( | ) |
Return the ticks taken to record an interval of time with ArchIntervalTimer, as measured at startup time.
int64_t pxr::ArchTicksToNanoseconds | ( | uint64_t | nTicks | ) |
Convert a duration measured in "ticks", as returned by ArchGetTickTime()
, to nanoseconds.
An example to test the timing routines would be:
double pxr::ArchTicksToSeconds | ( | uint64_t | nTicks | ) |
Convert a duration measured in "ticks", as returned by ArchGetTickTime()
, to seconds.
uint64_t pxr::ArchSecondsToTicks | ( | double | seconds | ) |
Convert a duration in seconds to "ticks", as returned by ArchGetTickTime()
.
double pxr::ArchGetNanosecondsPerTick | ( | ) |
Get nanoseconds per tick.
Useful when converting ticks obtained from ArchTickTime()
uint64_t pxr::Arch_MeasureExecutionTime | ( | uint64_t | maxTicks, |
bool * | reachedConsensus, | ||
void const * | m, | ||
uint64_t(* | callM )(void const *, int) ) |
uint64_t pxr::ArchMeasureExecutionTime | ( | Fn const & | fn, |
uint64_t | maxTicks = 1e7, | ||
bool * | reachedConsensus = nullptr ) |
Run fn
repeatedly attempting to determine a consensus fastest execution time with low noise, for up to maxTicks
, then return the consensus fastest execution time.
If a consensus is not reached in that time, return a best estimate instead. If reachedConsensus
is not null, set it to indicate whether or not a consensus was reached. This function ignores maxTicks
greater than 5 billion ticks and runs for up to 5 billion ticks instead. The fn
will run for an indeterminate number of times, so it should be side-effect free. Also, it should do essentially the same work on every invocation so that timing its execution makes sense.
void * pxr::ArchReserveVirtualMemory | ( | size_t | numBytes | ) |
Reserve numBytes
bytes of virtual memory.
Call ArchCommitVirtualMemory() on subranges to write to and read from the memory. Return nullptr in case of an error; check errno.
bool pxr::ArchCommitVirtualMemoryRange | ( | void * | start, |
size_t | numBytes ) |
Make the range of numBytes
bytes starting at start
available for reading and writing.
The range must be within one previously reserved by ArchReserveVirtualMemory(). It is not an error to commit a range that was previously partly or fully committed. Return false in case of an error; check errno.
bool pxr::ArchFreeVirtualMemory | ( | void * | start, |
size_t | numBytes ) |
Return memory obtained with ArchReserveVirtualMemory() to the system.
The start
argument must be the value returned from a previous call to ArchReserveVirtualMemory, and numBytes
must match the argument from that call. Memory within the range may not be accessed after this call. Return false in case of an error; check errno.
bool pxr::ArchSetMemoryProtection | ( | void const * | start, |
size_t | numBytes, | ||
ArchMemoryProtection | protection ) |
Change the memory protection on the pages containing start
and start
+ numBytes
to protection
.
Return true if the protection is changed successfully. Return false in case of an error; check errno. This function rounds start
to the nearest lower page boundary. On POSIX systems, ArchProtectReadWrite and ArchProtectReadWriteCopy are the same, on Windows they differ but the Windows API documentation does not make it clear what using ReadWrite means for a private file-backed mapping.
int pxr::ArchVsnprintf | ( | char * | str, |
size_t | size, | ||
const char * | format, | ||
va_list | ap ) |
Return the number of characters (not including the null character) necessary for a particular sprintf into a string.
ArchVsnprintf
guarantees the C99 behavior of vsnprintf on all systems: it returns the number of bytes (not including the terminating null character) needed to actually print the requested string. If size
indicates that str
has enough capacity to hold the result, then the function actually prints into str
.
You probably want to use the functionality of this call via TfStringPrintf()
.
std::string pxr::ArchStringPrintf | ( | const char * | fmt, |
... ) |
Returns a string formed by a printf()-like specification.
ArchStringPrintf()
is a memory-safe architecture-independent way of forming a string using printf()-like formatting. For example,
The function is safe only to the extent that the arguments match the formatting string. In particular, be careful to pass strings themselve into ArchStringPrintf()
as in the above example (i.e. caller.c_str()
as opposed to just passing caller
).
std::string pxr::ArchVStringPrintf | ( | const char * | fmt, |
va_list | ap ) |
Returns a string formed by a printf()-like specification.
ArchVStringPrintf()
is equivalent to ArchStringPrintf()
except that it is called with a va_list
instead of a variable number of arguments. ArchVStringPrintf()
does not call the va_end
macro. Consequently, the value of ap
is undefined after the call. A functions that calls ArchVStringPrintf()
should call va_end(ap)
itself afterwards.
StaticInit pxr::Arch_PerLibInit< StaticInit >::init |