Expand description
Rust wrapper for the aws-c-common library. For testing purposes only.
For interacting with AWS services, use the aws-sdk-rust crate instead.
Structs
Mark a pointer as being safe to share between threads.
struct aws_atomic_var represents an atomic variable - a value which can hold an integer or pointer
that can be manipulated atomically. struct aws_atomic_vars should normally only be manipulated
with atomics methods defined in this header.
Represents a length-delimited binary string or buffer. If byte buffer points
to constant memory or memory that should otherwise not be freed by this
struct, set allocator to NULL and free function will be a no-op.
Represents a movable pointer within a larger binary string or buffer.
Base stucture for caches, used the linked hash table implementation.
Dispatch table to dispatch cli commands from.
command_name should be the exact string for the command you want to handle from the command line.
Pattern-struct that functions as a base “class” for all statistics structures. To conform
to the pattern, a statistics structure must have its first member be the category. In that
case it becomes “safe” to cast from aws_crt_statistics_base to the specific statistics structure
based on the category value.
Base structure for all statistics handler implementations.
Vtable for functions that all statistics handlers must implement
The start and end time, in milliseconds-since-epoch, that a set of statistics was gathered over.
Represents an element in the hash table. Various operations on the hash
table may provide pointers to elements stored within the hash table;
generally, calling code may alter value, but must not alter key (or any
information used to compute key’s hash code).
Simple linked hash table. Preserves insertion order, and can be iterated in insertion order.
Linked-List node stored in the table. This is the node type that will be returned in
aws_linked_hash_table_get_iteration_list().
Options for aws_logger_init_standard().
Set
filename to open a file for logging and close it when the logger cleans up.
Set file to use a file that is already open, such as stderr or stdout.We separate the log level function from the log call itself so that we can do the filter check in the macros (see
below)
Lockless ring buffer implementation that is thread safe assuming a single thread acquires and a single thread
releases. For any other use case (other than the single-threaded use-case), you must manage thread-safety manually.
Data representing a URI. uri_str is always allocated and filled in.
The other portions are merely storing offsets into uri_str.
Arguments for building a URI instance. All members must
be initialized before passing them to aws_uri_init().
key/value pairs for a query string. If the query fragment was not in format key=value, the fragment value
will be stored in key
Hash table data structure. This module provides an automatically resizing
hash table implementation for general purpose use. The hash table stores a
mapping between void * keys and values; it is expected that in most cases,
these will point to a structure elsewhere in the heap, instead of inlining a
key or value into the hash table element itself.
Constants
Messages will be delivered, even if dynamic allocation is required. Default.
Only memory from the bus’s internal buffer will be used (if a buffer size is supplied at bus creation time).
If the buffer is full, older buffered messages will be discarded to make room for newer messages.
Message delivery is immediate, and therefore reliable by definition
Specifies acquire-release order; if this operation acts as a load, it acts as an
acquire operation; if it acts as a store, it acts as a release operation; if it’s
a load-store, it does both.
Specifies acquire ordering. No reads or writes on the current thread can be
reordered to happen before this operation. This is typically paired with a release
ordering; any writes that happened on the releasing operation will be visible
after the paired acquire operation.
No particular ordering constraints are guaranteed relative to other
operations at all; we merely ensure that the operation itself is atomic.
Specifies release order. No reads or writes can be reordered to come after this
operation. Typically paired with an acquire operation.
Specifies acquire-release order; if this operation acts as a load, it acts as an
acquire operation; if it acts as a store, it acts as a release operation; if it’s
a load-store, it does both.
Statics
If an option has an argument, when the option is encountered, this will be set to the argument portion.
Initialized to 1 (for where the first argument would be). As arguments are parsed, this number is the index
of the next argument to parse. Reset this to 1 to parse another set of arguments, or to rerun the parser.
If 0x02 was returned by aws_cli_getopt_long(), this value will be set to the argument encountered.
Functions
Adds [num] arguments (expected to be of size_t), and returns the result in *r.
If the result overflows, returns AWS_OP_ERR; otherwise returns AWS_OP_SUCCESS.
Inexpensive (constant time) check of data-structure invariants.
Compare two arrays.
Return whether their contents are equivalent.
NULL may be passed as the array pointer if its length is declared to be 0.
Compare an array and a null-terminated string.
Returns true if their contents are equivalent.
The array should NOT contain a null-terminator, or the comparison will always return false.
NULL may be passed as the array pointer if its length is declared to be 0.
Perform a case-insensitive string comparison of an array and a null-terminated string.
Return whether their contents are equivalent.
The array should NOT contain a null-terminator, or the comparison will always return false.
NULL may be passed as the array pointer if its length is declared to be 0.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Perform a case-insensitive string comparison of two arrays.
Return whether their contents are equivalent.
NULL may be passed as the array pointer if its length is declared to be 0.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
A convenience function for sorting lists of (const struct aws_string *) elements. This can be used as a
comparator for aws_array_list_sort. It is just a simple wrapper around aws_string_compare.
Copies the elements from from to to. If to is in static mode, it must at least be the same length as from. Any data
in to will be overwritten in this copy.
Ensures that the array list has enough capacity to store a value at the specified index. If there is not already
enough capacity, and the list is in dynamic mode, this function will attempt to allocate more memory, expanding the
list. In static mode, if ‘index’ is beyond the maximum index, AWS_ERROR_INVALID_INDEX will be raised.
If in dynamic mode, shrinks the allocated array size to the minimum amount necessary to store its elements.
Swap elements at the specified indices, which must be within the bounds of the array.
Print a backtrace from either the current stack, or (if provided) the current exception/signal
call_site_data is siginfo_t* on POSIX, and LPEXCEPTION_POINTERS on Windows, and can be null
Cleans up a message bus, including notifying all remaining listeners to close
Allocates and initializes a message bus
Sends a message to any listeners. payload will live until delivered, and then the destructor (if
provided) will be called. Note that anything payload references must also live at least until it is destroyed.
Will return AWS_OP_ERR if the bus is closing/has been closed
Subscribes a listener to a message type. user_data’s lifetime is the responsibility of the subscriber.
Unsubscribe a listener from a specific message. This is only necessary if the listener has lifetime concerns.
Otherwise, the listener will be called with an address of AWS_BUS_ADDRESS_CLOSE, which indicates that user_data
can be cleaned up if necessary and the listener will never be called again.
Appends a sub-buffer to the specified buffer.
Copies from to to. If to is too small, AWS_ERROR_DEST_COPY_TOO_SMALL will be
returned. dest->len will contain the amount of data actually copied to dest.
Copy contents of cursor to buffer, then update cursor to reference the memory stored in the buffer.
If buffer is too small, AWS_ERROR_DEST_COPY_TOO_SMALL will be returned.
Copies a single byte into
to. If to is too small, the buffer will be grown appropriately and
the old contents copied over, before the byte is appended.Copies a single byte into
to. If to is too small, the buffer will be grown appropriately and
the old contents copied over, before the byte is appended.Writes the uri decoding of a UTF-8 cursor to a buffer,
replacing %xx escapes by their single byte equivalent.
For example, reading “a%20b_c” would write “a b_c”.
Copies from to to. If to is too small, the buffer will be grown appropriately and
the old contents copied to, before the new contents are appended.
Copies
from to to. If to is too small, the buffer will be grown appropriately and
the old contents copied over, before the new contents are appended.Writes the uri query param encoding (passthrough alnum + ‘-’ ‘_’ ‘~’ ‘.’) of a UTF-8 cursor to a buffer
For example, reading “a b_c” would write “a%20b_c”.
Writes the uri path encoding of a cursor to a buffer. This is the modified version of rfc3986 used by
sigv4 signing.
Appends a unformatted JSON string representation of the aws_json_value into the passed byte buffer.
The byte buffer is expected to be already initialized so the function can append the JSON into it.
Appends a formatted JSON string representation of the aws_json_value into the passed byte buffer.
The byte buffer is expected to already be initialized so the function can append the JSON into it.
Appends ‘\0’ at the end of the buffer.
Copies from to to while converting bytes via the passed in lookup table.
If to is too small, AWS_ERROR_DEST_COPY_TOO_SMALL will be
returned. to->len will contain its original size plus the amount of data actually copied to to.
Concatenates a variable number of struct aws_byte_buf * into destination.
Number of args must be greater than 1. If dest is too small,
AWS_ERROR_DEST_COPY_TOO_SMALL will be returned. dest->len will contain the
amount of data actually copied to dest.
Equivalent to calling aws_byte_buf_secure_zero and then aws_byte_buf_clean_up
on the buffer.
Compare two aws_byte_buf structures.
Return whether their contents are equivalent.
Compare an aws_byte_buf and a null-terminated string.
Returns true if their contents are equivalent.
The buffer should NOT contain a null-terminator, or the comparison will always return false.
Perform a case-insensitive string comparison of an aws_byte_buf and a null-terminated string.
Return whether their contents are equivalent.
The buffer should NOT contain a null-terminator, or the comparison will always return false.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Perform a case-insensitive string comparison of two aws_byte_buf structures.
Return whether their contents are equivalent.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
For creating a byte buffer from a null-terminated string literal.
Init buffer with contents of multiple cursors, and update cursors to reference the memory stored in the buffer.
Each cursor arg must be an
struct aws_byte_cursor *. NULL must be passed as the final arg.
NOTE: Do not append/grow/resize buffers initialized this way, or the cursors will end up referencing invalid memory.
Returns AWS_OP_SUCCESS in case of success.
AWS_OP_ERR is returned if memory can’t be allocated or the total cursor length exceeds SIZE_MAX.Initializes an aws_byte_buf structure base on another valid one.
Requires: *src and *allocator are valid objects.
Ensures: *dest is a valid aws_byte_buf with a new backing array dest->buffer
which is a copy of the elements from src->buffer.
Copies src buffer into dest and sets the correct len and capacity.
A new memory zone is allocated for dest->buffer. When dest is no longer needed it will have to be cleaned-up using
aws_byte_buf_clean_up(dest).
Dest capacity and len will be equal to the src len. Allocator of the dest will be identical with parameter allocator.
If src buffer is null the dest will have a null buffer with a len and a capacity of 0
Returns AWS_OP_SUCCESS in case of success or AWS_OP_ERR when memory can’t be allocated.
Reads ‘filename’ into ‘out_buf’. If successful, ‘out_buf’ is allocated and filled with the data;
It is your responsibility to call ‘aws_byte_buf_clean_up()’ on it. Otherwise, ‘out_buf’ remains
unused. In the very unfortunate case where some API needs to treat out_buf as a c_string, a null terminator
is appended, but is not included as part of the length field.
Evaluates the set of properties that define the shape of all valid aws_byte_buf structures.
It is also a cheap check, in the sense it run in constant time (i.e., no loops or recursion).
Attempts to increase the capacity of a buffer to the requested capacity
Convenience function that attempts to increase the capacity of a buffer relative to the current
length.
Resets the len of the buffer to 0, but does not free the memory. The buffer can then be reused.
Optionally zeroes the contents, if the “zero_contents” flag is true.
Sets all bytes of buffer to zero and resets len to zero.
Write specified number of bytes from array to byte buffer.
Writes a 16-bit integer in network byte order (big endian) to buffer.
Writes low 24-bits (3 bytes) of an unsigned integer in network byte order (big endian) to buffer.
Ex: If x is 0x00AABBCC then {0xAA, 0xBB, 0xCC} is written to buffer.
Writes a 32-bit integer in network byte order (big endian) to buffer.
Writes a 64-bit integer in network byte order (big endian) to buffer.
Writes a 32-bit float in network byte order (big endian) to buffer.
Writes a 64-bit float in network byte order (big endian) to buffer.
Copies all bytes from buffer to buffer.
Copies all bytes from buffer to buffer.
Copies all bytes from string to buf.
Without increasing buf’s capacity, write as much as possible from advancing_cursor into buf.
Copies one byte to buffer.
Writes one byte repeatedly to buffer (like memset)
Tests if the given aws_byte_cursor has at least len bytes remaining. If so,
*buf is advanced by len bytes (incrementing ->ptr and decrementing ->len),
and an aws_byte_cursor referring to the first len bytes of the original *buf
is returned. Otherwise, an aws_byte_cursor with ->ptr = NULL, ->len = 0 is
returned.
Behaves identically to aws_byte_cursor_advance, but avoids speculative
execution potentially reading out-of-bounds pointers (by returning an
empty ptr in such speculated paths).
Lexical (byte value) comparison of two byte cursors
Lexical (byte value) comparison of two byte cursors where the raw values are sent through a lookup table first
Compare two aws_byte_cursor structures.
Return whether their contents are equivalent.
Compare an aws_byte_cursor and an aws_byte_buf.
Return whether their contents are equivalent.
Perform a case-insensitive string comparison of an aws_byte_cursor and an aws_byte_buf.
Return whether their contents are equivalent.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Compare an aws_byte_cursor and a null-terminated string.
Returns true if their contents are equivalent.
The cursor should NOT contain a null-terminator, or the comparison will always return false.
Perform a case-insensitive string comparison of an aws_byte_cursor and a null-terminated string.
Return whether their contents are equivalent.
The cursor should NOT contain a null-terminator, or the comparison will always return false.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Perform a case-insensitive string comparison of two aws_byte_cursor structures.
Return whether their contents are equivalent.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Search for an exact byte match inside a cursor. The first match will be returned. Returns AWS_OP_SUCCESS
on successful match and first_find will be set to the offset in input_str, and length will be the remaining length
from input_str past the returned offset. If the match was not found, AWS_OP_ERR will be returned and
AWS_ERROR_STRING_MATCH_NOT_FOUND will be raised.
Creates an aws_byte_cursor from an existing string.
Evaluates the set of properties that define the shape of all valid aws_byte_cursor structures.
It is also a cheap check, in the sense it runs in constant time (i.e., no loops or recursion).
Shrinks a byte cursor from the left for as long as the supplied predicate is true
No copies, no buffer allocations. Iterates over input_str, and returns the
next substring between split_on instances relative to previous substr.
Behaves similar to strtok with substr being used as state for next split.
Reads specified length of data from byte cursor and copies it to the
destination array.
Reads as many bytes from cursor as size of buffer, and copies them to buffer.
Reads a 16-bit value in network byte order from cur, and places it in host
byte order into var.
Reads an unsigned 24-bit value (3 bytes) in network byte order from cur,
and places it in host byte order into 32-bit var.
Ex: if cur’s next 3 bytes are {0xAA, 0xBB, 0xCC}, then var becomes 0x00AABBCC.
Reads a 32-bit value in network byte order from cur, and places it in host
byte order into var.
Reads a 64-bit value in network byte order from cur, and places it in host
byte order into var.
Reads a 32-bit value in network byte order from cur, and places it in host
byte order into var.
Reads a 64-bit value in network byte order from cur, and places it in host
byte order into var.
Reads 2 hex characters from ASCII/UTF-8 text to produce an 8-bit number.
Accepts both lowercase ‘a’-‘f’ and uppercase ‘A’-‘F’.
For example: “0F” produces 15.
Reads a single byte from cursor, placing it in *var.
Shrinks a byte cursor from the right for as long as the supplied predicate is true
Returns true if the byte cursor’s range of bytes all satisfy the predicate
No copies, no buffer allocations. Fills in output with a list of
aws_byte_cursor instances where buffer is an offset into the input_str and
len is the length of that string in the original buffer.
No copies, no buffer allocations. Fills in output with a list of aws_byte_cursor instances where buffer is
an offset into the input_str and len is the length of that string in the original buffer. N is the max number of
splits, if this value is zero, it will add all splits to the output.
Return true if the input starts with the prefix (exact byte comparison).
Return true if the input starts with the prefix (case-insensitive).
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Shrinks a byte cursor from both sides for as long as the supplied predicate is true
Read entire cursor as ASCII/UTF-8 unsigned base-10 number.
Stricter than strtoull(), which allows whitespace and inputs that start with “0x”
Read entire cursor as ASCII/UTF-8 unsigned base-16 number with NO “0x” prefix.
Clears all items from the cache.
Cleans up the cache. Elements in the cache will be evicted and cleanup
callbacks will be invoked.
Finds element in the cache by key. If found, *p_value will hold the stored value, and AWS_OP_SUCCESS will be
returned. If not found, AWS_OP_SUCCESS will be returned and *p_value will be NULL.
Returns the number of elements in the cache.
Initializes the first-in-first-out cache. Sets up the underlying linked hash table.
Once
max_items elements have been added, the oldest(first-in) item will
be removed. For the other parameters, see aws/common/hash_table.h. Hash table
semantics of these arguments are preserved.Initializes the last-in-first-out cache. Sets up the underlying linked hash table.
Once
max_items elements have been added, the latest(last-in) item will
be removed. For the other parameters, see aws/common/hash_table.h. Hash table
semantics of these arguments are preserved.Initializes the Least-recently-used cache. Sets up the underlying linked hash table.
Once
max_items elements have been added, the least recently used item will be removed. For the other parameters,
see aws/common/hash_table.h. Hash table semantics of these arguments are preserved.(Yes the one that was the answer
to that interview question that one time).Puts
p_value at key. If an element is already stored at key it will be replaced. If the cache is already full,
an item will be removed based on the cache policy.Removes item at
key from the cache.Dispatches the current command line arguments with a subcommand from the second input argument in argv[], if
dispatch table contains a command that matches the argument. When the command is dispatched, argc and argv will be
updated to reflect the new argument count. The cli options are required to come after the subcommand. If either, no
dispatch was found or there was no argument passed to the program, this function will return AWS_OP_ERR. Check
aws_last_error() for details on the error.
@param argc number of arguments passed to int main()
@param argv the arguments passed to int main()
@param parse_cb, optional, specify NULL if you don’t want to handle this. This argument is for parsing “meta”
commands from the command line options prior to dispatch occurring.
@param dispatch_table table containing functions and command name to dispatch on.
@param table_length numnber of entries in dispatch_table.
@return AWS_OP_SUCCESS(0) on success, AWS_OP_ERR(-1) on failure
A mostly compliant implementation of posix getopt_long(). Parses command-line arguments. argc is the number of
command line arguments passed in argv. optstring contains the legitimate option characters. The option characters
coorespond to aws_cli_option::val. If the character is followed by a :, the option requires an argument. If it is
followed by ‘::’, the argument is optional (not implemented yet).
Resets global parser state for use in another parser run for the application.
Shuts down the internal datastructures used by aws-c-common.
Initializes internal datastructures used by aws-c-common.
Must be called before using any functionality in aws-c-common.
Cleans up a condition variable.
Initializes a condition variable.
Notifies/Wakes all waiting threads.
Notifies/Wakes one waiting thread
Waits the calling thread on a notification from another thread.
Waits the calling thread on a notification from another thread. Times out after time_to_wait. time_to_wait is in
nanoseconds.
Waits the calling thread on a notification from another thread. Times out after time_to_wait. time_to_wait is in
nanoseconds. If predicate returns false, the wait is reentered, otherwise control returns to the caller.
Waits the calling thread on a notification from another thread. If predicate returns false, the wait is reentered,
otherwise control returns to the caller.
Returns true if a cpu feature is supported, false otherwise.
completely destroys a statistics handler. The handler’s cleanup function must clean up the impl portion completely
(including its allocation, if done separately).
Queries the frequency (via an interval in milliseconds) which a statistics handler would like to be informed
of statistics.
Submits a list of statistics objects to a statistics handler for processing
returns the difference of a and b (a - b) in seconds.
Initializes dt to be the time represented in milliseconds since unix epoch.
Initializes dt to be the time represented in seconds.millis since unix epoch.
Initializes dt to be the time represented by date_str in format ‘fmt’. Returns AWS_OP_SUCCESS if the
string was successfully parsed, returns AWS_OP_ERR if parsing failed.
aws_date_time_init variant that takes a byte_cursor rather than a byte_buf
Initializes dt to be the current system time.
Copies the current time as a formatted short date string in local time into output_buf. If buffer is too small, it
will return AWS_OP_ERR. A good size suggestion is AWS_DATE_TIME_STR_MAX_LEN bytes. AWS_DATE_FORMAT_AUTO_DETECT is not
allowed.
Copies the current time as a formatted date string in local time into output_buf. If buffer is too small, it will
return AWS_OP_ERR. A good size suggestion is AWS_DATE_TIME_STR_MAX_LEN bytes. AWS_DATE_FORMAT_AUTO_DETECT is not
allowed.
Copies the current time as a formatted short date string in utc time into output_buf. If buffer is too small, it will
return AWS_OP_ERR. A good size suggestion is AWS_DATE_TIME_STR_MAX_LEN bytes. AWS_DATE_FORMAT_AUTO_DETECT is not
allowed.
Copies the current time as a formatted date string in utc time into output_buf. If buffer is too small, it will
return AWS_OP_ERR. A good size suggestion is AWS_DATE_TIME_STR_MAX_LEN bytes. AWS_DATE_FORMAT_AUTO_DETECT is not
allowed.
Returns an instance of system default thread options.
Fill a buffer with unpredictably random bytes, suitable for cryptographic use.
Get an unpredictably random 8bit number, suitable for cryptographic use.
Get an unpredictably random 16bit number, suitable for cryptographic use.
Get an unpredictably random 32bit number, suitable for cryptographic use.
Get an unpredictably random 64bit number, suitable for cryptographic use.
Creates a directory if it doesn’t currently exist. If the directory already exists, it’s ignored and assumed
successful.
Deletes a directory. If the directory is not empty, this will fail unless the recursive parameter is set to true.
If recursive is true then the entire directory and all of its contents will be deleted. If it is set to false,
the directory will be deleted only if it is empty. Returns AWS_OP_SUCCESS if the operation was successful. Otherwise,
aws_last_error() will contain the error that occurred. If the directory doesn’t exist, AWS_OP_SUCCESS is still
returned.
Cleanup and deallocate iterator
Gets the aws_directory_entry value for iterator at the current position. Returns NULL if the iterator contains no
entries.
Creates a read-only iterator of a directory starting at path. If path is invalid or there’s any other error
condition, NULL will be returned. Call aws_last_error() for the exact error in that case.
Moves the iterator to the next entry. Returns AWS_OP_SUCCESS if another entry is available, or AWS_OP_ERR with
AWS_ERROR_LIST_EMPTY as the value for aws_last_error() if no more entries are available.
Moves the iterator to the previous entry. Returns AWS_OP_SUCCESS if another entry is available, or AWS_OP_ERR with
AWS_ERROR_LIST_EMPTY as the value for aws_last_error() if no more entries are available.
Returns true if the directory currently exists. Otherwise, it returns false.
Moves directory at from to to.
Returns AWS_OP_SUCCESS if the operation was successful. Otherwise,
aws_last_error() will contain the error that occurred.
Traverse a directory starting at path.
Deletes a file. Returns AWS_OP_SUCCESS if the operation was successful. Otherwise,
aws_last_error() will contain the error that occurred. If the file doesn’t exist, AWS_OP_SUCCESS is still returned.
Don’t use this. It never should have been added in the first place. It’s now deprecated.
Opens file at file_path using mode. Returns the FILE pointer if successful.
For a group, returns the number of CPUs it contains.
Returns the logical processor groupings on the system (such as multiple numa nodes).
Fills in cpu_ids_array with the cpu_id’s for the group. To obtain the size to allocate for cpu_ids_array
and the value for argument for cpu_ids_array_length, call aws_get_cpu_count_for_group().
Returns the hard limit for max io handles (max fds in unix terminology). This limit is one more than the actual
limit. This limit cannot be increased without sudo permissions.
Returns the current user’s home directory.
Returns the current process’s PID (process id).
@return PID as int
Returns the directory separator used by the local platform
Returns the soft limit for max io handles (max fds in unix terminology). This limit is one more than the actual
limit. The soft limit can be changed up to the hard limit by any process regardless of permissions.
Cross platform friendly version of gmtime_r
Case-insensitive hash function for array containing ASCII or UTF-8 text.
Convenience hash function for struct aws_byte_cursor.
Hash is same as used on the string bytes by aws_hash_c_string.
Case-insensitive hash function for aws_byte_cursors stored in an aws_hash_table.
For case-sensitive hashing, use aws_hash_byte_cursor_ptr().
Convenience hash function for NULL-terminated C-strings
Convenience eq callback for NULL-terminated C-strings
Convenience destroy callback for AWS strings
Convenience eq callback for AWS strings
Returns an iterator to be used for iterating through a hash table.
Iterator will already point to the first element of the table it finds,
which can be accessed as iter.element.
Deletes the element currently pointed-to by the hash iterator.
After calling this method, the element member of the iterator
should not be accessed until the next call to aws_hash_iter_next.
Returns true if iterator is done iterating through table, false otherwise.
If this is true, the iterator will not include an element of the table.
Given a pointer to a hash_iter, checks that it is well-formed, with all data-structure invariants.
Updates iterator so that it points to next element of hash table.
Convenience hash function which hashes the pointer value directly,
without dereferencing. This can be used in cases where pointer identity
is desired, or where a uintptr_t is encoded into a const void *.
Convenience hash function for struct aws_strings.
Hash is same as used on the string bytes by aws_hash_c_string.
Deletes every element from map and frees all associated memory.
destroy_fn will be called for each element. aws_hash_table_init
must be called before reusing the hash table.
Removes every element from the hash map. destroy_fn will be called for
each element.
Attempts to locate an element at key. If no such element was found,
creates a new element, with value initialized to NULL. In either case, a
pointer to the element is placed in *p_elem.
Compares two hash tables for equality. Both hash tables must have equivalent
key comparators; values will be compared using the comparator passed into this
function. The key hash function does not need to be equivalent between the
two hash tables.
Attempts to locate an element at key. If the element is found, a
pointer to the value is placed in *p_elem; if it is not found,
*pElem is set to NULL. Either way, AWS_OP_SUCCESS is returned.
Iterates through every element in the map and invokes the callback on
that item. Iteration is performed in an arbitrary, implementation-defined
order, and is not guaranteed to be consistent across invocations.
Returns the current number of entries in the table.
Initializes a hash map with initial capacity for ‘size’ elements
without resizing. Uses hash_fn to compute the hash of each element.
equals_fn to compute equality of two keys. Whenever an element is
removed without being returned, destroy_key_fn is run on the pointer
to the key and destroy_value_fn is run on the pointer to the value.
Either or both may be NULL if a callback is not desired in this case.
Best-effort check of hash_table_state data-structure invariants
Moves the hash table in ‘from’ to ‘to’. After this move, ‘from’ will
be identical to the state of the original ‘to’ hash table, and ‘to’
will be in the same state as if it had been passed to aws_hash_table_clean_up
(that is, it will have no memory allocated, and it will be safe to
either discard it or call aws_hash_table_clean_up again).
Inserts a new element at key, with the given value. If another element
exists at that key, the old element will be overwritten; both old key and
value objects will be destroyed.
Removes element at key. Always returns AWS_OP_SUCCESS.
Removes element already known (typically by find()).
Safely swaps two hash tables. Note that we swap the entirety of the hash
table, including which allocator is associated.
Get ticks in nanoseconds (usually 100 nanosecond precision) on the high resolution clock (most-likely TSC). This
clock has no bearing on the actual system time. On success, timestamp will be set.
Returns true iff the character is a directory separator on ANY supported platform.
Like isalnum(), but ignores C locale.
Returns true if ch has the value of ASCII/UTF-8: ‘a’-‘z’, ‘A’-‘Z’, or ‘0’-‘9’.
Like isalpha(), but ignores C locale.
Returns true if ch has the value of ASCII/UTF-8: ‘a’-‘z’ or ‘A’-‘Z’.
Like isdigit().
Returns true if ch has the value of ASCII/UTF-8: ‘0’-‘9’.
Like isspace(), but ignores C locale.
Return true if ch has the value of ASCII/UTF-8: space (0x20), form feed (0x0C),
line feed (0x0A), carriage return (0x0D), horizontal tab (0x09), or vertical tab (0x0B).
Like isxdigit().
Returns true if ch has the value of ASCII/UTF-8: ‘0’-‘9’, ‘a’-‘f’, or ‘A’-‘F’.
@brief iterates through values of an array.
iteration is sequential starting with 0th element.
@param array array to iterate over.
@param on_value callback for when value is encountered.
@param user_data user data to pass back in callback.
@return AWS_OP_SUCCESS when iteration finishes completely or exits early,
AWS_OP_ERR if value is not an array.
@brief iterates through members of the object.
iteration is sequential in order fields were initially parsed.
@param object object to iterate over.
@param on_member callback for when member is encountered.
@param user_data user data to pass back in callback.
@return AWS_OP_SUCCESS when iteration finishes completely or exits early,
AWS_OP_ERR if value is not an object.
Returns the aws_json_value at the given index in the array aws_json_value.
@param array The array aws_json_value.
@param index The index of the aws_json_value you want to access.
@return A pointer to the aws_json_value at the given index in the array, otherwise NULL.
Returns the number of items in the array aws_json_value.
@param array The array aws_json_value.
@return The number of items in the array_json_value.
Adds a aws_json_value to the given array aws_json_value.
Adds a aws_json_value to a object aws_json_value.
Checks whether two json values are equivalent.
@param a first value to compare.
@param b second value to compare.
@param is_case_sensitive case sensitive compare or not.
@return True is values are equal, false otherwise
Removes the aws_json_value from memory. If the aws_json_value is a object or array, it will also destroy
attached aws_json_values as well.
Duplicates json value.
@param value first value to compare.
@return duplicated value. NULL and last error set if value cannot be duplicated.
Gets the boolean of a boolean aws_json_value.
@param value The boolean aws_json_value.
@param output The boolean
@return AWS_OP_SUCCESS if the value is a boolean, otherwise AWS_OP_ERR.
Returns the aws_json_value at the given key.
@param object The object aws_json_value you want to get the value from.
@param key The key that the aws_json_value is at. Is case sensitive.
@return The aws_json_value at the given key, otherwise NULL.
Gets the number of a number aws_json_value.
@param value The number aws_json_value.
@param output The number
@return AWS_OP_SUCCESS if the value is a number, otherwise AWS_OP_ERR.
Gets the string of a string aws_json_value.
@param value The string aws_json_value.
@param output The string
@return AWS_OP_SUCCESS if the value is a string, otherwise AWS_OP_ERR.
Checks if there is a aws_json_value at the given key.
@param object The value aws_json_value you want to check a key in.
@param key The key that you want to check. Is case sensitive.
@return True if a aws_json_value is found.
Checks if the aws_json_value is a array.
@param value The aws_json_value to check.
@return True if the aws_json_value is a array aws_json_value, otherwise false.
Checks if the aws_json_value is a boolean.
@param value The aws_json_value to check.
@return True if the aws_json_value is a boolean aws_json_value, otherwise false.
Checks if the aws_json_value is a null aws_json_value.
@param value The aws_json_value to check.
@return True if the aws_json_value is a null aws_json_value, otherwise false.
Checks if the aws_json_value is a number.
@param value The aws_json_value to check.
@return True if the aws_json_value is a number aws_json_value, otherwise false.
Checks if the aws_json_value is a object aws_json_value.
@param value The aws_json_value to check.
@return True if the aws_json_value is a object aws_json_value, otherwise false.
Checks if the aws_json_value is a string.
@param value The aws_json_value to check.
@return True if the aws_json_value is a string aws_json_value, otherwise false.
Creates a new array aws_json_value and returns a pointer to it.
Creates a new boolean aws_json_value with the given boolean and returns a pointer to it.
Parses the JSON string and returns a aws_json_value containing the root of the JSON.
@param allocator The allocator used to create the value
@param string The string containing the JSON.
@return The root aws_json_value of the JSON.
Creates a new null aws_json_value and returns a pointer to it.
Creates a new number aws_json_value with the given number and returns a pointer to it.
Creates a new object aws_json_value and returns a pointer to it.
Creates a new string aws_json_value with the given string and returns a pointer to it.
Removes the aws_json_value at the given index in the array aws_json_value.
@param array The array aws_json_value.
@param index The index containing the aws_json_value you want to remove.
@return AWS_OP_SUCCESS if the aws_json_value at the index was removed.
Will return AWS_OP_ERR if the array passed is invalid or if the index
passed is out of range.
Removes the aws_json_value at the given key.
@param object The object aws_json_value you want to remove a aws_json_value in.
@param key The key that the aws_json_value is at. Is case sensitive.
@return AWS_OP_SUCCESS if the aws_json_value was removed.
Will return AWS_OP_ERR if the object passed is invalid or if the value
at the key cannot be found.
Cleans up the table. Elements in the table will be evicted and cleanup
callbacks will be invoked.
Clears all items from the table.
Finds element in the table by key. If found, AWS_OP_SUCCESS will be
returned. If not found, AWS_OP_SUCCESS will be returned and *p_value will be
NULL.
Finds element in the table by key. If found, AWS_OP_SUCCESS will be returned and the item will be moved to the back
of the list.
If not found, AWS_OP_SUCCESS will be returned and *p_value will be NULL.
returns number of elements in the table.
returns the underlying linked list for iteration.
Initializes the table. Sets up the underlying hash table and linked list.
For the other parameters, see aws/common/hash_table.h. Hash table
semantics of these arguments are preserved.
Move the aws_linked_hash_table_node to the end of the list.
Puts
p_value at key. If an element is already stored at key it will be replaced.Removes item at
key from the table.Cross platform friendly version of localtime_r
Converts a log level to a c-string constant. Intended primarily to support building log lines that
include the level in them, i.e.
Get subject name from log subject.
Cleans up all resources used by the logger; simply invokes the clean_up v-function
Gets the aws logger used globally across the process.
Gets the aws logger used globally across the process if the logging level is at least the inputted level.
Sets the aws logger used globally across the process. Not thread-safe. Must only be called once.
Sets the current logging level for the logger. Loggers are not require to support this.
@param logger logger to set the log level for
@param level new log level for the logger
@return AWS_OP_SUCCESS if the level was successfully set, AWS_OP_ERR otherwise
Returns lookup table to go from ASCII/UTF-8 hex character to a number (0-15).
Non-hex characters map to 255.
Valid examples:
‘0’ -> 0
‘F’ -> 15
‘f’ -> 15
Invalid examples:
’ ’ -> 255
‘Z’ -> 255
‘\0’ -> 255
Returns a lookup table for bytes that is the identity transformation with the exception
of uppercase ascii characters getting replaced with lowercase characters. Used in
caseless comparisons.
Accesses the most-recently-used element and returns its value.
Accesses the least-recently-used element, sets it to most-recently-used
element, and returns the value.
Returns at least
size of memory ready for usage. In versions v0.6.8 and prior, this function was allowed to return
NULL. In later versions, if allocator->mem_acquire() returns NULL, this function will assert and exit. To handle
conditions where OOM is not a fatal error, allocator->mem_acquire() is responsible for finding/reclaiming/running a
GC etc…before returning.Allocates many chunks of bytes into a single block. Expects to be called with alternating void ** (dest), size_t
(size). The first void ** will be set to the root of the allocation. Alignment is assumed to be sizeof(intmax_t).
Allocates a block of memory for an array of num elements, each of them size bytes long, and initializes all its bits
to zero. In versions v0.6.8 and prior, this function was allowed to return NULL.
In later versions, if allocator->mem_calloc() returns NULL, this function will assert and exit. To handle
conditions where OOM is not a fatal error, allocator->mem_calloc() is responsible for finding/reclaiming/running a
GC etc…before returning.
Attempts to adjust the size of the pointed-to memory buffer from oldsize to
newsize. The pointer (*ptr) may be changed if the memory needs to be
reallocated.
Releases ptr back to whatever allocated it.
Nothing happens if ptr is NULL.
Cleans up internal resources.
Initializes a new platform instance of mutex.
Blocks until it acquires the lock. While on some platforms such as Windows,
this may behave as a reentrant mutex, you should not treat it like one. On
platforms it is possible for it to be non-reentrant, it will be.
Attempts to acquire the lock but returns immediately if it can not.
While on some platforms such as Windows, this may behave as a reentrant mutex,
you should not treat it like one. On platforms it is possible for it to be non-reentrant, it will be.
Note: For windows, minimum support server version is Windows Server 2008 R2 [desktop apps | UWP apps]
Releases the lock.
Returns true if a file or path exists, otherwise, false.
Checks that the backpointer at a specific index of the queue is
NULL or points to a correctly allocated aws_priority_queue_node.
Checks that the backpointers of the priority queue satisfy validity
constraints.
Checks that the backpointers of the priority queue are either NULL
or correctly allocated to point at aws_priority_queue_nodes. This
check is O(n), as it accesses every backpointer in a loop, and thus
shouldn’t be used carelessly.
Current allocated capacity for the queue, in dynamic mode this grows over time, in static mode, this will never
change.
Cleans up any internally allocated memory and resets the struct for reuse or deletion.
Initializes a priority queue struct for use. This mode will grow memory automatically (exponential model)
Default size is the inital size of the queue
item_size is the size of each element in bytes. Mixing items types is not supported by this API.
pred is the function that will be used to determine priority.
Initializes a priority queue struct for use. This mode will not allocate any additional memory. When the heap fills
new enqueue operations will fail with AWS_ERROR_PRIORITY_QUEUE_FULL.
Set of properties of a valid aws_priority_queue.
Copies the element of the highest priority, and removes it from the queue.. Complexity: O(log(n)).
If queue is empty, AWS_ERROR_PRIORITY_QUEUE_EMPTY will be raised.
Copies item into the queue and places it in the proper priority order. Complexity: O(log(n)).
Copies item into the queue and places it in the proper priority order. Complexity: O(log(n)).
Removes a specific node from the priority queue. Complexity: O(log(n))
After removing a node (using either _remove or _pop), the backpointer set at push_ref time is set
to a sentinel value. If this sentinel value is passed to aws_priority_queue_remove,
AWS_ERROR_PRIORITY_QUEUE_BAD_NODE will be raised. Note, however, that passing uninitialized
aws_priority_queue_nodes, or ones from different priority queues, results in undefined behavior.
Current number of elements in the queue
Obtains a pointer to the element of the highest priority. Complexity: constant time.
If queue is empty, AWS_ERROR_PRIORITY_QUEUE_EMPTY will be raised.
Equality function which compares pointer equality.
Increments a ref-counter’s ref count
Initializes a ref-counter structure. After initialization, the ref count will be 1.
Decrements a ref-counter’s ref count. Invokes the on_zero callback if the ref count drops to zero
@param ref_count ref-counter to decrement the count for
@return the value of the decremented ref count
TODO: this needs to be a private function (wait till we have the cmake story
better before moving it though). It should be external for the purpose of
other libs we own, but customers should not be able to hit it without going
out of their way to do so.
Connects log subject strings with log subject integer values
Attempts to acquire
requested_size buffer and stores the result in dest if successful. Returns AWS_OP_SUCCESS if
the requested size was available for use, AWS_OP_ERR otherwise.Attempts to acquire
requested_size buffer and stores the result in dest if successful. If not available, it will
attempt to acquire anywhere from 1 byte to requested_size. Returns AWS_OP_SUCCESS if some buffer space is available
for use, AWS_OP_ERR otherwise.Cleans up a ring buffer allocator instance. Does not clean up the ring buffer.
Returns true if the memory in
buf was vended by this ring buffer, false otherwise.
Make sure buf->buffer and ring_buffer->allocation refer to the same memory region.Cleans up the ring buffer’s resources.
Initializes a ring buffer with an allocation of size
size. Returns AWS_OP_SUCCESS on a successful initialization,
AWS_OP_ERR otherwise.Releases
buf back to the ring buffer for further use. RELEASE MUST HAPPEN in the SAME ORDER AS ACQUIRE.
If you do not, your application, and possibly computers within a thousand mile radius, may die terrible deaths,
and the local drinking water will be poisoned for generations
with fragments of what is left of your radioactive corrupted memory.Currently this API is implemented using popen on Posix system and
_popen on Windows to capture output from running a command. Note
that popen only captures stdout, and doesn’t provide an option to
capture stderr. We will add more options, such as acquire stderr
in the future so probably will alter the underlying implementation
as well.
Cleans up internal resources.
Initializes a new platform instance of mutex.
Blocks until it acquires the lock. While on some platforms such as Windows,
this may behave as a reentrant mutex, you should not treat it like one. On
platforms it is possible for it to be non-reentrant, it will be.
Releases the lock.
Attempts to acquire the lock but returns immediately if it can not.
While on some platforms such as Windows, this may behave as a reentrant mutex,
you should not treat it like one. On platforms it is possible for it to be non-reentrant, it will be.
Note: For windows, minimum support server version is Windows Server 2008 R2 [desktop apps | UWP apps]
Computes the length of a c string in bytes assuming the character set is either ASCII or UTF-8. If no NULL character
is found within max_read_len of str, AWS_ERROR_C_STRING_BUFFER_NOT_NULL_TERMINATED is raised. Otherwise, str_len
will contain the string length minus the NULL character, and AWS_OP_SUCCESS will be returned.
Securely zeroes a memory buffer. This function will attempt to ensure that
the compiler will not optimize away this zeroing operation.
Sets the new soft limit for io_handles (max fds). This can be up to the hard limit but may not exceed it.
If the string was dynamically allocated, clones it. If the string was statically allocated (i.e. has no allocator),
returns the original string.
Compares lexicographical ordering of two strings. This is a binary
byte-by-byte comparison, treating bytes as unsigned integers. It is suitable
for either textual or binary data and is unaware of unicode or any other byte
encoding. If both strings are identical in the bytes of the shorter string,
then the longer string is lexicographically after the shorter.
Deallocate string.
Zeroes out the data bytes of string and then deallocates the memory.
Not safe to run on a string created with AWS_STATIC_STRING_FROM_LITERAL.
Returns true if bytes of string are the same, false otherwise.
Returns true if bytes of string and buffer are the same, false otherwise.
Returns true if bytes of string and buffer are equivalent, using a case-insensitive comparison.
Returns true if bytes of string and cursor are the same, false otherwise.
Returns true if bytes of string and cursor are equivalent, using a case-insensitive comparison.
Returns true if bytes of strings are equivalent, using a case-insensitive comparison.
Returns true if bytes of string are equivalent, using a case-insensitive comparison.
Allocate a new string with the same contents as array.
Allocate a new string with the same contents as buf.
Constructor functions which copy data from null-terminated C-string or array of bytes.
Allocate a new string with the same contents as cursor.
Allocate a new string with the same contents as another string.
Converts a c-string constant to a log level value. Uses case-insensitive comparison
and simply iterates all possibilities until a match or nothing remains. If no match
is found, AWS_OP_ERR is returned.
Get ticks in nanoseconds (usually 100 nanosecond precision) on the system clock. Reflects actual system time via
nanoseconds since unix epoch. Use with care since an inaccurately set clock will probably cause bugs. On success,
timestamp will be set.
Init an aws_task
Removes task from the scheduler and invokes the task with the AWS_TASK_STATUS_CANCELED status.
Empties and executes all queued tasks, passing the AWS_TASK_STATUS_CANCELED status to the task function.
Cleans up any memory allocated, and prepares the instance for reuse or deletion.
Returns whether the scheduler has any scheduled tasks.
next_task_time (optional) will be set to time of the next task, note that 0 will be set if tasks were
added via aws_task_scheduler_schedule_now() and UINT64_MAX will be set if no tasks are scheduled at all.
Initializes a task scheduler instance.
Sequentially execute all tasks scheduled to run at, or before current_time.
AWS_TASK_STATUS_RUN_READY will be passed to the task function as the task status.
Schedules a task to run at time_to_run.
The task should not be cleaned up or modified until its function is executed.
Schedules a task to run immediately.
The task should not be cleaned up or modified until its function is executed.
Convert a status value to a c-string suitable for logging
Cleans up the thread handle. Don’t call this on a managed thread. If you wish to join the thread, you must join
before calling this function.
Adds a callback to the chain to be called when the current thread joins.
Callbacks are called from the current thread, in the reverse order they
were added, after the thread function returns.
If not called from within an aws_thread, has no effect.
Sleeps the current thread by nanos.
Returns the thread id of the calling thread.
Decrements the count of unjoined threads in the managed thread system. Used by managed threads and
event loop threads. Additional usage requires the user to join corresponding threads themselves and
correctly increment/decrement even in the face of launch/join errors.
Gets the detach state of the thread. For example, is it safe to call join on
this thread? Has it been detached()?
Gets the id of thread
Converts an aws_thread_id_t to a c-string. For portability, aws_thread_id_t
must not be printed directly. Intended primarily to support building log
lines that include the thread id in them. The parameter
buffer must
point-to a char buffer of length bufsz == AWS_THREAD_ID_T_REPR_BUFSZ. The
thread id representation is returned in buffer.Increments the count of unjoined threads in the managed thread system. Used by managed threads and
event loop threads. Additional usage requires the user to join corresponding threads themselves and
correctly increment/decrement even in the face of launch/join errors.
Initializes a new platform specific thread object struct (not the os-level
thread itself).
Joins the calling thread to a thread instance. Returns when thread is
finished. Calling this from the associated OS thread will cause a deadlock.
Blocking call that waits for all managed threads to complete their join call. This can only be called
from the main thread or a non-managed thread.
Creates an OS level thread and associates it with func. context will be passed to func when it is executed.
options will be applied to the thread if they are applicable for the platform.
Acquire a reference to the scheduler.
Cancel a task that has been scheduled. The cancellation callback will be invoked in the background thread.
This function is slow, so please don’t do it in the hot path for your code.
Creates a new instance of a thread scheduler. This object receives scheduled tasks and executes them inside a
background thread. On success, this function returns an instance with a ref-count of 1. On failure it returns NULL.
Release a reference to the scheduler.
Schedules a task to run in the future. time_to_run is the absolute time from the system hw_clock.
Schedules a task to run as soon as possible.
Overrides how long, in nanoseconds, that aws_thread_join_all_managed will wait for threads to complete.
A value of zero will result in an unbounded wait.
Compare thread ids.
Cross platform friendly version of timegm
Convert a c library io error into an aws error.
Disconnects log subject strings with log subject integer values
Returns the authority portion of the uri (host[:port]). If it was not present, this was a request uri. In that
case, the value will be empty.
Returns the ‘host_name’ portion of the authority. If no authority was present, this value will be empty.
Initializes uri to values specified in options. Returns AWS_OP_SUCCESS, on success, AWS_OP_ERR on failure.
After calling this function, the parts can be accessed.
Parses ‘uri_str’ and initializes uri. Returns AWS_OP_SUCCESS, on success, AWS_OP_ERR on failure.
After calling this function, the parts can be accessed.
Returns the path portion of the uri. If the original value was empty, this value will be “/”.
Returns the path and query portion of the uri (i.e., the thing you send across the wire).
Returns the port portion of the authority if it was present, otherwise, returns 0.
If this is 0, it is the users job to determine the correct port based on scheme and protocol.
Returns the query string portion of the uri, minus the ‘?’. If not present, this value will be empty.
For iterating over the params in the uri query string.
param is an in/out argument used to track progress, it MUST be zeroed out to start.
If true is returned, param contains the value of the next param.
If false is returned, there are no further params.Parses query string and stores the parameters in ‘out_params’. Returns AWS_OP_SUCCESS on success and
AWS_OP_ERR on failure. The user is responsible for initializing out_params with item size of struct aws_query_param.
The user is also responsible for cleaning up out_params when finished.
Returns the scheme portion of the uri (e.g. http, https, ftp, ftps, etc…). If the scheme was not present
in the uri, the returned value will be empty. It is the users job to determine the appropriate defaults
if this field is empty, based on protocol, port, etc…
Writes the contents of the body of node into out_body. out_body is an output parameter in this case. Upon success,
out_body will contain the body of the node.
Traverse node and invoke on_node_encountered when a nested node is encountered.
Allocates an xml parser.
Parse the doc until the end or until a callback rejects the document.
on_node_encountered will be invoked when the root node is encountered.
Type Definitions
Prototype for a comparator function for sorting elements.
Signature for function argument to trim APIs
Invoked when a subcommand is encountered. argc and argv[] begins at the command encounterd.
command_name is the name of the command being handled.
The common-specific range of the aws_crt_statistics_category cross-library enum.
Prototype for a hash table key or value destructor function pointer.
Prototype for a hash table equality check function pointer.
Prototype for a key hashing function pointer.
@brief callback for iterating members of an object
Iteration can be controlled as follows:
@brief callback for iterating values of an array.
Iteration can be controlled as follows:
Controls what log calls pass through the logger and what log calls get filtered out.
If a log level has a value of X, then all log calls using a level <= X will appear, while
those using a value > X will not occur.
Log subject is a way of designating the topic of logging.
@deprecated Use int64_t instead for offsets in public APIs.
Invoked during calls to aws_directory_traverse() as an entry is encountered. entry will contain
the parsed directory entry info.
A scheduled function.
Specifies the join strategy used on an aws_thread, which in turn controls whether or not a thread participates
in the managed thread system. The managed thread system provides logic to guarantee a join on all participating
threads at the cost of laziness (the user cannot control when joins happen).
Callback for when an xml node is encountered in the document. As a user you have a few options: