Expand description
Rust wrapper for the aws-c-io library. For testing purposes only.
For interacting with AWS services, use the aws-sdk-rust crate instead.
Structs
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.
Args for creating a new channel.
event_loop to use for IO and tasks. on_setup_completed will be invoked when
the setup process is finished It will be executed in the event loop’s thread.
on_shutdown_completed will be executed upon channel shutdown.
aws_client_bootstrap handles creation and setup of channels that communicate via socket with a specific endpoint.
aws_client_bootstrap creation options.
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.
Socket channel handler statistics record
Tls channel handler statistics record
The custom key operation that is used when performing a mutual TLS handshake. This can
be extended to provide custom private key operations, like PKCS11 or similar.
vtable for aws_custom_key_op_handler.
Options for exponential backoff retry strategy. el_group must be set, any other option, if set to 0 will signify
“use defaults”
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).
should you absolutely disdain the default implementation, feel free to implement your own.
Base class for input streams.
Note: when you implement one input stream, the ref_count needs to be initialized to clean up the resource when
reaches to zero.
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)
Handle to a loaded PKCS#11 library.
Options for aws_pkcs11_lib_new()
aws_server_bootstrap manages listening sockets, creating and setting up channels to handle each incoming connection.
Arguments to setup a server socket listener which will also negotiate and configure TLS.
This creates a socket listener bound to
host and ‘port’ using socket options options, and TLS options
tls_options. incoming_callback will be invoked once an incoming channel is ready for use and TLS is
finished negotiating, or if an error is encountered. shutdown_callback will be invoked once the channel has
shutdown. destroy_callback will be invoked after the server socket listener is destroyed, and all associated
connections and channels have finished shutting down. Immediately after the shutdown_callback returns, the channel
is cleaned up automatically. All callbacks are invoked in the thread of the event-loop that listener is assigned to.Socket-based channel creation options.
This struct exists as a graceful way to pass many arguments when
calling init-with-pkcs11 functions on aws_tls_ctx_options (this also makes
it easy to introduce optional arguments in the future).
Instances of this struct should only exist briefly on the stack.
A struct containing all of the data needed for a private key operation when
making a mutual TLS connection. This struct contains the data that needs
to be operated on, like performing a sign operation or a decrypt operation.
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
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.
Default behavior that accommodates most use cases.
C_Initialize() is called on creation, and “already-initialized” errors are ignored.
C_Finalize() is never called, just in case another part of your
application is still using the PKCS#11 library.
Skip calling C_Initialize() and C_Finalize().
Use this if your application has already initialized the PKCS#11 library,
and you do not want C_Initialize() called again.
C_Initialize() is called on creation and C_Finalize() is called on cleanup.
If C_Initialize() reports that’s it’s already initialized, this is treated as an error.
Use this if you need perfect cleanup (ex: running valgrind with –leak-check).
Doesn’t count against any budgets. This could be something like a 401 challenge in Http.
This is a server error that isn’t explicitly throttling but is considered by the client
to be something that should be retried.
This is an error where the server explicitly told the client to back off, such as a 429 or 503 Http error.
This is a connection level error such as a socket timeout, socket connect error, tls negotiation timeout etc…
Typically these should never be applied for non-idempotent request types since in this scenario, it’s impossible
to know whether the operation had a side effect on the server.
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.
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.
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 ‘\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.
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.
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.
Prevent a channel’s memory from being freed.
Any number of users may acquire a hold to prevent a channel and its handlers from being unexpectedly freed.
Any user which acquires a hold must release it via aws_channel_release_hold().
Memory will be freed once all holds are released and aws_channel_destroy() has been called.
Acquires a message from the event loop’s message pool. size_hint is merely a hint, it may be smaller than you
requested and you are responsible for checking the bounds of it. If the returned message is not large enough, you
must send multiple messages.
Fetches the current timestamp from the event-loop’s clock, in nanoseconds.
Mark the channel, along with all slots and handlers, for destruction.
Must be called after shutdown has completed.
Can be called from any thread assuming ‘aws_channel_shutdown()’ has completed.
Note that memory will not be freed until all users which acquired holds on the channel via
aws_channel_acquire_hold(), release them via aws_channel_release_hold().
Retrieves an object by key from the event loop’s local storage.
Fetches the event loop the channel is a part of.
Calls destroy on handler’s vtable
Calls on_window_update on handler’s vtable.
Calls initial_window_size on handler’s vtable.
Calls process_read_message on handler’s vtable
Calls process_write_message on handler’s vtable.
calls shutdown_direction on handler’s vtable.
Allocates new channel, Unless otherwise specified all functions for channels and channel slots must be executed
within that channel’s event-loop’s thread. channel_options are copied.
Stores an object by key in the event loop’s local storage.
Release a hold on the channel’s memory, allowing it to be freed.
This may be called before or after aws_channel_destroy().
Removes an object by key from the event loop’s local storage.
Schedules a task to run on the event loop at the specified time.
This is the ideal way to move a task into the correct thread. It’s also handy for context switches.
Use aws_channel_current_clock_time() to get the current time in nanoseconds.
This function is safe to call from any thread.
Schedules a task to run on the event loop as soon as possible.
This is the ideal way to move a task into the correct thread. It’s also handy for context switches.
This function is safe to call from any thread.
Schedules a task to run on the event loop as soon as possible.
Instrument a channel with a statistics handler. While instrumented with a statistics handler, the channel
will periodically report per-channel-handler-specific statistics about handler performance and state.
Misc TLS related
Initiates shutdown of the channel. Shutdown will begin with the left-most slot. Each handler will invoke
‘aws_channel_slot_on_handler_shutdown_complete’ once they’ve finished their shutdown process for the read direction.
Once the right-most slot has shutdown in the read direction, the process will start shutting down starting on the
right-most slot. Once the left-most slot has shutdown in the write direction, ‘callbacks->shutdown_completed’ will be
invoked in the event loop’s thread.
Convenience function that invokes aws_channel_acquire_message_from_pool(),
asking for the largest reasonable DATA message that can be sent in the write direction,
with upstream overhead accounted for.
Fetches the downstream read window. This gives you the information necessary to honor the read window. If you call
send_message() and it exceeds this window, the message will be rejected.
Issues a window update notification upstream (to the left.)
Inserts to ‘to_add’ the end of the channel. Note that the first call to
aws_channel_slot_new() adds it to the channel implicitly.
inserts ‘to_add’ to the position immediately to the left of slot. Note that the first call to
aws_channel_slot_new() adds it to the channel implicitly.
inserts ‘to_add’ to the position immediately to the right of slot. Note that the first call to
aws_channel_slot_new() adds it to the channel implicitly.
Allocates and initializes a new slot for use with the channel. If this is the first slot in the channel, it will
automatically be added to the channel as the first slot. For all subsequent calls on a given channel, the slot will
need to be added to the channel via. the aws_channel_slot_insert_right(), aws_channel_slot_insert_end(), and
aws_channel_slot_insert_left() APIs.
Called by handlers once they have finished their shutdown in the ‘dir’ direction. Propagates the shutdown process
to the next handler in the channel.
Removes slot from the channel and deallocates the slot and its handler.
Replaces remove with new_slot. Deallocates remove and its handler.
Sends a message to the adjacent slot in the channel based on dir. Also does window size checking.
Sets the handler for a slot, the slot will also call get_current_window_size() and propagate a window update
upstream.
Initiates shutdown on slot. callbacks->on_shutdown_completed will be called
once the shutdown process is completed.
Fetches the current overhead of upstream handlers. This provides a hint to avoid fragmentation if you care.
Initializes channel_task for use.
Returns true if the caller is on the event loop’s thread. If false, you likely need to use
aws_channel_schedule_task(). This function is safe to call from any thread.
A way for external processes to force a read by the data-source channel handler. Necessary in certain cases, like
when a server channel finishes setting up its initial handlers, a read may have already been triggered on the
socket (the client’s CLIENT_HELLO tls payload, for example) and absent further data/notifications, this data
would never get processed.
Increments a client bootstrap’s ref count, allowing the caller to take a reference to it.
Create the client bootstrap.
Sets up a client socket channel.
Decrements a client bootstrap’s ref count. When the ref count drops to zero, the bootstrap will be destroyed.
When using TLS, if ALPN is used, this callback will be invoked from the channel. The returned handler will be added
to the channel.
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.
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
Cleans up socket channel handler statistics
Initializes socket channel handler statistics
Resets socket channel handler statistics for the next gather interval. Calculate-once results are left alone.
Cleans up tls channel handler statistics
Initializes tls channel handler statistics
Resets tls channel handler statistics for the next gather interval. Calculate-once results are left alone.
Increases the reference count for the passed-in aws_custom_key_op_handler and returns it.
Calls the on_key_operation vtable function. See aws_custom_key_op_handler_vtable for function details.
Decreases the reference count for the passed-in aws_custom_key_op_handler and returns NULL.
WARNING! do not call this function directly (getaddrinfo()): it blocks. Provide a pointer to this function for other
resolution functions.
Returns an instance of system default thread options.
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.
Cancels task.
This function must be called from the event loop’s thread, and is only guaranteed
to work properly on tasks scheduled from within the event loop’s thread.
The task will be executed with the AWS_TASK_STATUS_CANCELED status inside this call.
Common cleanup code for all implementations.
This is only called from the *destroy() function of event loop implementations.
Gets the current timestamp for the event loop’s clock, in nanoseconds. This function is thread-safe.
Invokes the destroy() fn for the event loop implementation.
If the event loop is still in a running state, this function will block waiting on the event loop to shutdown.
If you do not want this function to block, call aws_event_loop_stop() manually first.
If the event loop is shared by multiple threads then destroy must be called by exactly one thread. All other threads
must ensure their API calls to the event loop happen-before the call to destroy.
Fetches an object from the event-loop’s data store. Key will be taken as the memory address of the memory pointed to
by key. This function is not thread safe and should be called inside the event-loop’s thread.
Cleans up resources (user_data) associated with the I/O eventing subsystem for a given handle. This should only
ever be necessary in the case where you are cleaning up an event loop during shutdown and its thread has already
been joined.
Returns the current load factor (however that may be calculated). If the event-loop is not invoking
aws_event_loop_register_tick_start() and aws_event_loop_register_tick_end(), this value will always be 0.
Increments the reference count on the event loop group, allowing the caller to take a reference to it.
Fetches the next loop for use. The purpose is to enable load balancing across loops. You should not depend on how
this load balancing is done as it is subject to change in the future. Currently it uses the “best-of-two” algorithm
based on the load factor of each loop.
Creates an event loop group, with clock, number of loops to manage, and the function to call for creating a new
event loop.
Initializes an event loop group with platform defaults. If max_threads == 0, then the
loop count will be the number of available processors on the machine / 2 (to exclude hyper-threads).
Otherwise, max_threads will be the number of event loops in the group.
Creates an event loop group, with clock, number of loops to manage, the function to call for creating a new
event loop, and also pins all loops to hw threads on the same cpu_group (e.g. NUMA nodes). Note:
If el_count exceeds the number of hw threads in the cpu_group it will be clamped to the number of hw threads
on the assumption that if you care about NUMA, you don’t want hyper-threads doing your IO and you especially
don’t want IO on a different node.
Creates an event loop group, with clock, number of loops to manage, the function to call for creating a new
event loop, and also pins all loops to hw threads on the same cpu_group (e.g. NUMA nodes). Note:
If el_count exceeds the number of hw threads in the cpu_group it will be ignored on the assumption that if you
care about NUMA, you don’t want hyper-threads doing your IO and you especially don’t want IO on a different node.
Decrements an event loop group’s ref count. When the ref count drops to zero, the event loop group will be
destroyed.
Initializes common event-loop data structures.
This is only called from the *new() function of event loop implementations.
Creates an instance of the default event loop implementation for the current architecture and operating system.
Creates an instance of the default event loop implementation for the current architecture and operating system using
extendable options.
Puts an item object the event-loop’s data store. Key will be taken as the memory address of the memory pointed to by
key. The lifetime of item must live until remove or a put item overrides it. This function is not thread safe and
should be called inside the event-loop’s thread.
For event-loop implementations to use for providing metrics info to the base event-loop. This enables the
event-loop load balancer to take into account load when vending another event-loop to a caller.
For event-loop implementations to use for providing metrics info to the base event-loop. This enables the
event-loop load balancer to take into account load when vending another event-loop to a caller.
Removes an object from the event-loop’s data store. Key will be taken as the memory address of the memory pointed to
by key. If removed_item is not null, the removed item will be moved to it if it exists. Otherwise, the default
deallocation strategy will be used. This function is not thread safe and should be called inside the event-loop’s
thread.
Triggers the running of the event loop. This function must not block. The event loop is not active until this
function is invoked. This function can be called again on an event loop after calling aws_event_loop_stop() and
aws_event_loop_wait_for_stop_completion().
The event loop will schedule the task and run it at the specified time.
Use aws_event_loop_current_clock_time() to query the current time in nanoseconds.
Note that cancelled tasks may execute outside the event loop thread.
This function may be called from outside or inside the event loop thread.
The event loop will schedule the task and run it on the event loop thread as soon as possible.
Note that cancelled tasks may execute outside the event loop thread.
This function may be called from outside or inside the event loop thread.
Triggers the event loop to stop, but does not wait for the loop to stop completely.
This function may be called from outside or inside the event loop thread. It is safe to call multiple times.
This function is called from destroy().
Subscribes on_event to events on the event-loop for handle. events is a bitwise concatenation of the events that were
received. The definition for these values can be found in aws_io_event_type. Currently, only
AWS_IO_EVENT_TYPE_READABLE and AWS_IO_EVENT_TYPE_WRITABLE are honored. You always are registered for error conditions
and closure. This function may be called from outside or inside the event loop thread. However, the unsubscribe
function must be called inside the event-loop’s thread.
Returns true if the event loop’s thread is the same thread that called this function, otherwise false.
Unsubscribes handle from event-loop notifications.
This function is not thread safe and should be called inside the event-loop’s thread.
Blocks until the event loop stops completely.
If you want to call aws_event_loop_run() again, you must call this after aws_event_loop_stop().
It is not safe to call this function from inside the event loop thread.
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.
Returns the current user’s home directory.
Returns the directory separator used by the local platform
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.
Cleans up the memory for
addressCopies
from to to.Moves
from to to. After this call, from is no longer usable. Though, it could be resused for another
move or copy operation.Increments the reference count on the host resolver, allowing the caller to take a reference to it.
get number of addresses for a given host.
Creates a host resolver with the default behavior. Here’s the behavior:
calls purge_cache on the vtable.
calls record_connection_failure on the vtable.
Decrements a host resolver’s ref count. When the ref count drops to zero, the resolver will be destroyed.
calls resolve_host on the vtable. config will be copied.
Increments the reference count on the input stream, allowing the caller to take a reference to it.
Decrements a input stream’s ref count. When the ref count drops to zero, the input stream will be destroyed.
Shuts down the internal datastructures used by aws-c-io.
Initializes internal datastructures used by aws-c-io.
Must be called before using any functionality in aws-c-io.
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’.
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.
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.
Acquires memory from the pool if available, otherwise, it attempts to allocate and returns the result.
Releases memory to the pool if space is available, otherwise frees
to_releaseAcquires a message from the pool if available, otherwise, it attempts to allocate. If a message is acquired,
note that size_hint is just a hint. the return value’s capacity will be set to the actual buffer size.
Initializes message pool using ‘msg_pool’ as the backing pool, ‘args’ is copied.
Releases message to the pool if space is available, otherwise frees
message
@param messageReturns true if a file or path exists, otherwise, false.
Clean up the read-end of the pipe.
This must be called on the thread of the connected event-loop.
Clean up the write-end of the pipe.
This must be called on the thread of the connected event-loop.
Get the event-loop connected to the read-end of the pipe.
This may be called on any thread.
Get the event-loop connected to the write-end of the pipe.
This may be called on any thread.
Opens an OS specific bidirectional pipe.
The read direction is stored in read_end. Write direction is stored in write_end.
Each end must be connected to an event-loop, and further calls to each end must happen on that event-loop’s thread.
Read data from the pipe into the destination buffer.
Attempts to read enough to fill all remaining space in the buffer, from
dst_buffer->len to dst_buffer->capacity.
dst_buffer->len is updated to reflect the buffer’s new length.
num_bytes_read (optional) is set to the total number of bytes read.
This function never blocks. If no bytes could be read without blocking, then AWS_OP_ERR is returned and
aws_last_error() code will be AWS_IO_READ_WOULD_BLOCK.
This must be called on the thread of the connected event-loop.Subscribe to be notified when the pipe becomes readable (edge-triggered), or an error occurs.
on_readable is invoked on the event-loop’s thread when the pipe has data to read, or the pipe has an error.
on_readable is invoked again any time the user reads all data, and then more data arrives.
Note that it will not be invoked again if the pipe still has unread data when more data arrives.
This must be called on the thread of the connected event-loop.Stop receiving notifications about events on the read-end of the pipe.
This must be called on the thread of the connected event-loop.
Initiates an asynchrous write from the source buffer to the pipe.
The data referenced by
src_buffer must remain in memory until the operation completes.
on_complete is called on the event-loop thread when the operation has either completed or failed.
The callback’s pipe argument will be NULL if the callback is invoked after the pipe has been cleaned up.
This must be called on the thread of the connected event-loop.Acquire a reference to a PKCS#11 library, preventing it from being cleaned up.
You must call aws_pkcs11_lib_release() when you are done with it.
This function returns whatever was passed in. It cannot fail.
Load and initialize a PKCS#11 library.
See
aws_pkcs11_lib_options for options.Release a reference to the PKCS#11 library.
When the last reference is released, the library is cleaned up.
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
Acquire a reference count on retry_strategy.
Attempts to acquire a retry token for use with retries. On success, on_acquired will be invoked when a token is
available, or an error will be returned if the timeout expires. partition_id identifies operations that should be
grouped together. This allows for more sophisticated strategies such as AIMD and circuit breaker patterns. Pass NULL
to use the global partition.
Creates a retry strategy using exponential backoff. This strategy does not perform any bookkeeping on error types and
success. There is no circuit breaker functionality in here. See the comments above for
aws_exponential_backoff_retry_options.
This is a retry implementation that cuts off traffic if it’s
detected that an endpoint partition is having availability
problems. This is necessary to keep from making outages worse
by scheduling work that’s unlikely to succeed yet increases
load on an already ailing system.
Releases a reference count on retry_strategy.
Schedules a retry based on the backoff and token based strategies. retry_ready is invoked when the retry is either
ready for execution or if it has been canceled due to application shutdown.
Increments reference count for token. This should be called any time you seat the token to a pointer you own.
Records a successful retry. This is used for making future decisions to open up token buckets, AIMD breakers etc…
some strategies such as exponential backoff will ignore this, but you should always call it after a successful
operation or your system will never recover during an outage.
Releases the reference count for token. This should always be invoked after either calling
aws_retry_strategy_schedule_retry() and failing, or after calling aws_retry_token_record_success().
Securely zeroes a memory buffer. This function will attempt to ensure that
the compiler will not optimize away this zeroing operation.
Increments a server bootstrap’s ref count, allowing the caller to take a reference to it.
Shuts down ‘listener’ and cleans up any resources associated with it. Any incoming channels on
listener will still
be active. destroy_callback will be invoked after the server socket listener is destroyed, and all associated
connections and channels have finished shutting down.Initializes the server bootstrap with
allocator and el_group. This object manages listeners, server connections,
and channels.Sets up a server socket listener. If you are planning on using TLS, use
aws_server_bootstrap_new_tls_socket_listener instead. This creates a socket listener bound to local_endpoint
using socket options options. incoming_callback will be invoked once an incoming channel is ready for use or if
an error is encountered. shutdown_callback will be invoked once the channel has shutdown. destroy_callback will
be invoked after the server socket listener is destroyed, and all associated connections and channels have finished
shutting down. Immediately after the shutdown_callback returns, the channel is cleaned up automatically. All
callbacks are invoked the thread of the event-loop that the listening socket is assigned toDecrements a server bootstrap’s ref count. When the ref count drops to zero, the bootstrap will be destroyed.
When using TLS, if ALPN is used, this callback will be invoked from the channel. The returned handler will be added
to the channel.
Assigns the socket to the event-loop. The socket will begin receiving read/write/error notifications after this call.
Binds the socket to a local address. In UDP mode, the socket is ready for
aws_socket_read() operations. In
connection oriented modes, you still must call aws_socket_listen() and aws_socket_start_accept() before using the
socket. local_endpoint is copied.Shuts down any pending operations on the socket, and cleans up state. The socket object can be re-initialized after
this operation. This function calls aws_socket_close. If you have not already called aws_socket_close() on the
socket, all of the rules for aws_socket_close() apply here. In this case it will not fail if you use the function
improperly, but on some platforms you will certainly leak memory.
Calls
close() on the socket and unregisters all io operations from the event loop. This function must be called
from the event-loop’s thread unless this is a listening socket. If it’s a listening socket it can be called from any
non-event-loop thread or the event-loop the socket is currently assigned to. If called from outside the event-loop,
this function will block waiting on the socket to close. If this is called from an event-loop thread other than
the one it’s assigned to, it presents the possibility of a deadlock, so don’t do it.Connects to a remote endpoint. In UDP, this simply binds the socket to a remote address for use with
aws_socket_write(), and if the operation is successful, the socket can immediately be used for write operations.Get the local address which the socket is bound to.
Raises an error if no address is bound.
Gets the latest error from the socket. If no error has occurred AWS_OP_SUCCESS will be returned. This function does
not raise any errors to the installed error handlers.
Gets the event-loop the socket is assigned to.
Socket handlers should be the first slot/handler in a channel. It interacts directly with the channel’s event loop
for read and write notifications. max_read_size is the maximum amount of data it will read from the socket
before a context switch (a continuation task will be scheduled).
Initializes a socket object with socket options. options will be copied.
Returns true if the socket is still open (doesn’t mean connected or listening, only that it hasn’t had close()
called.
TCP, LOCAL and VSOCK only. Sets up the socket to listen on the address bound to in
aws_socket_bind().Reads from the socket. This call is non-blocking and will return
AWS_IO_SOCKET_READ_WOULD_BLOCK if no data is
available. read is the amount of data read into buffer.Sets new socket options on the underlying socket. This is mainly useful in context of accepting a new connection via:
on_incoming_connection(). options is copied.Calls
shutdown() on the socket based on direction.TCP, LOCAL and VSOCK only. The socket will begin accepting new connections. This is an asynchronous operation. New
connections or errors will arrive via the
on_accept_result callback.TCP, LOCAL and VSOCK only. The listening socket will stop accepting new connections.
It is safe to call
aws_socket_start_accept() again after
this operation. This can be called from any thread but be aware,
on some platforms, if you call this from outside of the current event loop’s thread, it will block
until the event loop finishes processing the request for unsubscribe in it’s own thread.Subscribes on_readable to notifications when the socket goes readable (edge-triggered). Errors will also be recieved
in the callback.
Writes to the socket. This call is non-blocking and will attempt to write as much as it can, but will queue any
remaining portion of the data for write when available. written_fn will be invoked once the entire cursor has been
written, or the write failed or was cancelled.
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.
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.
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.
Creates a channel handler, for client or server mode, that handles alpn. This isn’t necessarily required
since you can always call aws_tls_handler_protocol in the aws_tls_on_negotiation_result_fn callback, but
this makes channel bootstrap easier to handle.
Creates a new client ctx. This ctx can be used for the lifetime of the application assuming you want the same
options for every outgoing connection. Options will be copied.
Creates a new tls channel handler in client mode. Options will be copied.
You must call aws_tls_client_handler_start_negotiation and wait on the
aws_tls_on_negotiation_result_fn callback before the handler can begin processing
application data.
Kicks off the negotiation process. This function must be called when in client mode to initiate the
TLS handshake. Once the handshake has completed the aws_tls_on_negotiation_result_fn will be invoked.
Cleans up resources in aws_tls_connection_options. This can be called immediately after initializing
a tls handler, or if using the bootstrap api, immediately after asking for a channel.
Copies ‘from’ to ‘to’
Initializes default connection options from an instance ot aws_tls_ctx.
Sets alpn list in the form <protocol1;protocol2;…>. A maximum of 4 protocols are supported.
alpn_list is copied. This value is already inherited from aws_tls_ctx, but the aws_tls_ctx is expensive,
and should be used across as many connections as possible. If you want to set this per connection, set it here.
Sets callbacks for use with a tls connection.
Sets server name to use for the SNI extension (supported everywhere), as well as x.509 validation. If you don’t
set this, your x.509 validation will likely fail.
Increments the reference count on the tls context, allowing the caller to take a reference to it.
Cleans up resources allocated by init_* functions
Initializes options for use with mutual tls in client mode.
cert and pkey are copied. cert and pkey are treated as PKCS#7 PEM
armored.
Initializes options for use with mutual tls in client mode.
cert_path and pkey_path are paths to files on disk. cert_path
and pkey_path are treated as PKCS#7 PEM armored. They are loaded
from disk and stored in buffers internally.
Initializes options for use with mutual tls in client mode.
cert_reg_path is the path to a system
installed certficate/private key pair. Example:
CurrentUser\MY\
Initializes options for use with mutual tls in client mode.
pkcs12 is a buffer containing a pkcs#12 certificate and private key; it is copied.
pkcs_pwd is the corresponding password for the pkcs#12 buffer; it is copied.
Initializes options for use with mutual tls in client mode.
pkcs12_path is a path to a file on disk containing a pkcs#12 file. The file is loaded
into an internal buffer. pkcs_pwd is the corresponding password for the pkcs#12 file; it is copied.
Initializes options for use with mutual TLS in client mode,
where private key operations are handled by custom code.
Initializes options for use with mutual TLS in client mode,
where a PKCS#11 library provides access to the private key.
tls options init stuff ***********************/
Initializes options with default client options
Initializes options for use with in server mode.
cert and pkey are copied. cert and pkey are treated as PKCS#7 PEM
armored.
Initializes options for use with in server mode.
cert_path and pkey_path are paths to files on disk. cert_path
and pkey_path are treated as PKCS#7 PEM armored. They are loaded
from disk and stored in buffers internally.
Initializes options for use with server mode.
cert_reg_path is the path to a system
installed certficate/private key pair. Example:
CurrentUser\MY\
Initializes options for use in server mode.
pkcs12 is a buffer containing a pkcs#12 certificate and private key; it is copied.
pkcs_pwd is the corresponding password for the pkcs#12 buffer; it is copied.
Initializes options for use in server mode.
pkcs12_path is a path to a file on disk containing a pkcs#12 file. The file is loaded
into an internal buffer. pkcs_pwd is the corresponding password for the pkcs#12 file; it is copied.
Override the default trust store. ca_file is a buffer containing a PEM armored chain of trusted CA certificates.
ca_file is copied.
Override the default trust store. ca_path is a path to a directory on disk containing trusted certificates. This is
only supported on Unix systems (otherwise this parameter is ignored). ca_file is a path to a file on disk containing
trusted certificates. ca_file is loaded from disk and stored in an internal buffer.
Sets alpn list in the form <protocol1;protocol2;…>. A maximum of 4 protocols are supported.
alpn_list is copied.
When implementing BYO_CRYPTO, if you need extra data to pass to your tls implementation, set it here. The lifetime of
extension_data must outlive the options object and be cleaned up after options is cleaned up.
@Deprecated
Sets the minimum TLS version to allow.
Enables or disables x.509 validation. Disable this only for testing. To enable mutual TLS in server mode,
set verify_peer to true.
Decrements a tls context’s ref count. When the ref count drops to zero, the object will be destroyed.
Returns a byte buffer by copy of the negotiated protocols. If there is no agreed upon protocol, len will be 0 and
buffer will be NULL.
Client mode only. This is the server name that was used for SNI and host name validation.
Not necessary if you are installing more handlers into the channel, but if you just want to have TLS for arbitrary
data and use the channel handler directly, this function allows you to write data to the channel and have it
encrypted.
Given enum, return string like: AWS_TLS_HASH_SHA256 -> “SHA256”
Returns true if alpn is available in the underlying tls implementation.
This function should always be called before setting an alpn list.
Returns true if this Cipher Preference is available in the underlying TLS implementation.
This function should always be called before setting a Cipher Preference
Complete a successful TLS private key operation by providing its output.
The output is copied into the TLS connection.
The operation is freed by this call.
Complete an failed TLS private key operation.
The TLS connection will fail.
The operation is freed by this call.
Returns the algorithm the operation digest is signed with.
If the implementation does not support the digest algorithm,
use aws_tls_key_operation_complete_with_error() to preventing stalling the TLS connection.
Returns the input data that needs to be operated on by the custom key operation.
Returns the algorithm the operation is expected to be operated with.
If the implementation does not support the signature algorithm,
use aws_tls_key_operation_complete_with_error() to preventing stalling the TLS connection.
Returns the type of operation that needs to be performed by the custom key operation.
If the implementation cannot perform the operation,
use aws_tls_key_operation_complete_with_error() to preventing stalling the TLS connection.
Given enum, return string like: AWS_TLS_SIGNATURE_RSA -> “RSA”
Creates a new server ctx. This ctx can be used for the lifetime of the application assuming you want the same
options for every incoming connection. Options will be copied.
Creates a new tls channel handler in server mode. Options will be copied.
You must wait on the aws_tls_on_negotiation_result_fn callback before the handler can begin processing
application data.
Given enum, return string like: AWS_TLS_SIGNATURE_RSA -> “RSA”
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…
Type Definitions
Prototype for a comparator function for sorting elements.
Signature for function argument to trim APIs
If ALPN is being used this function will be invoked by the channel once an ALPN message is received. The returned
channel_handler will be added to, and managed by, the channel.
Generic event function for channel lifecycle events.
Called after client bootstrap has been completely cleaned up, after its last refcount is released.
The common-specific range of the aws_crt_statistics_category cross-library enum.
Jitter mode for exponential backoff.
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.
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.
Invoked once an address has been resolved for host. The type in host_addresses is struct aws_host_address (by-value).
The caller does not own this memory and you must copy the host address before returning from this function if you
plan to use it later. For convenience, we’ve provided the aws_host_address_copy() and aws_host_address_clean_up()
functions.
Callback for when the pipe is readable (edge-triggered), or an error has occurred.
Afer subscribing, the callback is invoked when the pipe has data to read, or the pipe has an error.
The readable callback is invoked again any time the user reads all data, and then more data arrives.
Note that it will not be invoked again if the pipe still has unread data when more data arrives.
error_code of AWS_ERROR_SUCCESS indicates a readable event, and otherwise contains the value of the error.
user_data corresponds to the user_data passed into aws_pipe_subscribe_to_read_events().
This callback is always invoked on the read-end’s event-loop thread.Callback for when the asynchronous aws_pipe_write() operation has either completed or failed.
write_end will be NULL if this callback is invoked after the the write-end has been cleaned up,
this does not necessarily mean that the write operation failed.
error_code will be AWS_ERROR_SUCCESS if all data was written, or a code corresponding to the error.
src_buffer corresponds to the buffer passed into aws_pipe_write()
user_data corresponds to the user_data passed into aws_pipe_write().
This callback is always invoked on the write-end’s event-loop thread.Controls how aws_pkcs11_lib calls C_Initialize() and C_Finalize() on the PKCS#11 library.
Function signature for configuring your own resolver (the default just uses getaddrinfo()). The type in
output_addresses is struct aws_host_address (by-value). We assume this function blocks, hence this absurdly
complicated design.
Invoked after a successful call to aws_retry_strategy_schedule_retry(). This function will always be invoked if and
only if aws_retry_strategy_schedule_retry() returns AWS_OP_SUCCESS. It will never be invoked synchronously from
aws_retry_strategy_schedule_retry(). After attempting the operation, either call aws_retry_strategy_schedule_retry()
with an aws_retry_error_type or call aws_retry_token_record_success() and then release the token via.
aws_retry_token_release().
Invoked upon the acquisition, or failure to acquire a retry token. This function will always be invoked if and only
if aws_retry_strategy_acquire_retry_token() returns AWS_OP_SUCCESS. It will never be invoked synchronously from
aws_retry_strategy_acquire_retry_token(). Token will always be NULL if error_code is non-zero, and vice-versa. If
token is non-null, it will have a reference count of 1, and you must call aws_retry_token_release() on it later. See
the comments for aws_retry_strategy_on_retry_ready_fn for more info.
If TLS is being used, this function is called once the socket has received an incoming connection, the channel has
been initialized, and TLS has been successfully negotiated. A TLS handler has already been added to the channel. If
TLS negotiation fails, this function will be called with the corresponding error code.
Once the channel shuts down, this function will be invoked within the thread of
the event-loop that the channel is assigned to.
Once the server listener socket is finished destroying, and all the existing connections are closed, this fuction
will be invoked.
Called by a listening socket when either an incoming connection has been received or an error occurred.
Called in client mode when an outgoing connection has succeeded or an error has occurred.
If the connection was successful error_code will be AWS_ERROR_SUCCESS and the socket has already been assigned
to the event loop specified in aws_socket_connect().
Callback for when socket is either readable (edge-triggered) or when an error has occurred. If the socket is
readable, error_code will be AWS_ERROR_SUCCESS.
Callback for when the data passed to a call to aws_socket_write() has either completed or failed.
On success, error_code will be AWS_ERROR_SUCCESS.
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).
The hash algorithm of a TLS private key operation. Any custom private key operation handlers are expected to perform
operations on the input TLS data using the correct hash algorithm or fail the operation.
The TLS private key operation that needs to be performed by a custom private key operation handler when making
a connection using mutual TLS.
An enum for the current state of tls negotiation within a tls channel handler
Only used if the TLS handler is the last handler in the channel. This allows you to read any data that
was read and decrypted by the handler. If you have application protocol channel handlers, this function
is not necessary and certainly not recommended.
Invoked when an error occurs in the TLS state machine AFTER the handshake has completed. This function should only
be used in conjunction with the rules of aws_tls_on_data_read_fn.
Invoked upon completion of the TLS handshake. If successful error_code will be AWS_OP_SUCCESS, otherwise
the negotiation failed and immediately after this function is invoked, the channel will be shutting down.
The signature of a TLS private key operation. Any custom private key operation handlers are expected to perform
operations on the input TLS data using the correct signature algorithm or fail the operation.