Pigweed
C/C++ API Reference
|
Provides basic helpers for reading and writing UTF-8 encoded strings. More...
Typedefs | |
template<typename T > | |
using | AlignedAtomic = std::atomic< NaturallyAligned< T > > |
using | ByteSpan = span< std::byte > |
using | ConstByteSpan = span< const std::byte > |
template<typename T , size_t kCapacity = containers::internal::kGenericSized> | |
using | InlineAsyncDeque = BasicInlineAsyncDeque< T, uint16_t, kCapacity > |
template<typename ValueType , size_t kCapacity = containers::internal::kGenericSized> | |
using | InlineAsyncQueue = BasicInlineAsyncQueue< ValueType, uint16_t, kCapacity > |
template<typename ValueType , typename SizeType , size_t kCapacity = containers::internal::kGenericSized> | |
using | BasicInlineDeque = containers::internal::BasicInlineDequeImpl< ValueType, containers::internal::CountAndCapacity< SizeType >, kCapacity > |
template<typename T , size_t kCapacity = containers::internal::kGenericSized> | |
using | InlineDeque = BasicInlineDeque< T, uint16_t, kCapacity > |
template<typename T , size_t kCapacity = containers::internal::kGenericSized> | |
using | InlineQueue = BasicInlineQueue< T, uint16_t, kCapacity > |
template<size_t kMaxSizeBytes = containers::internal::kGenericSized> | |
using | InlineVarLenEntryQueue = BasicInlineVarLenEntryQueue< std::byte, kMaxSizeBytes > |
Variable-length entry queue that uses std::byte for the byte type. | |
template<typename T > | |
using | IntrusiveList = containers::future::IntrusiveList< T > |
template<typename FunctionType > | |
using | Function = fit::function_impl< function_internal::config::kInlineCallableSize, !function_internal::config::kEnableDynamicAllocation, FunctionType, PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE > |
template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize> | |
using | InlineFunction = fit::inline_function< FunctionType, inline_target_size > |
template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize, typename Allocator = PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE> | |
using | DynamicFunction = fit::function_impl< inline_target_size, false, FunctionType, Allocator > |
using | Closure = Function< void()> |
void -returning pw::Function that takes no arguments. | |
template<typename FunctionType > | |
using | Callback = fit::callback_impl< function_internal::config::kInlineCallableSize, !function_internal::config::kEnableDynamicAllocation, FunctionType, PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE > |
template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize> | |
using | InlineCallback = fit::inline_callback< FunctionType, inline_target_size > |
Version of pw::Callback that exclusively uses inline storage. | |
template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize, typename Allocator = PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE> | |
using | DynamicCallback = fit::callback_impl< inline_target_size, false, FunctionType, Allocator > |
Version of pw::Callback that supports dynamic allocation. | |
using | FlatMultiBuf = BasicMultiBuf<> |
Basic MultiBuf interface with mutable data. | |
using | FlatConstMultiBuf = BasicMultiBuf< MultiBufProperty::kConst > |
Basic MultiBuf interface with read-only data. | |
using | MultiBuf = BasicMultiBuf< MultiBufProperty::kLayerable > |
using | ConstMultiBuf = BasicMultiBuf< MultiBufProperty::kConst, MultiBufProperty::kLayerable > |
using | TrackedFlatMultiBuf = BasicMultiBuf< MultiBufProperty::kObservable > |
using | TrackedFlatConstMultiBuf = BasicMultiBuf< MultiBufProperty::kConst, MultiBufProperty::kObservable > |
using | TrackedMultiBuf = BasicMultiBuf< MultiBufProperty::kLayerable, MultiBufProperty::kObservable > |
using | TrackedConstMultiBuf = BasicMultiBuf< MultiBufProperty::kConst, MultiBufProperty::kLayerable, MultiBufProperty::kObservable > |
template<size_t kCapacity = string_impl::kGeneric> | |
using | InlineString = InlineBasicString< char, kCapacity > |
pw::InlineString is an alias of pw::InlineBasicString<char> and is equivalent to std::string . | |
template<size_t kCapacity = string_impl::kGeneric> | |
using | InlineByteString = InlineBasicString< std::byte, kCapacity > |
pw::InlineByteString is an alias of pw::InlineBasicString<std::byte> . InlineByteString may be used as a simple, efficient byte container. | |
using | DefaultThreadContext = ThreadContext< thread::backend::kDefaultStackSizeBytes > |
Alias for ThreadContext with the backend's default stack size. | |
using | ThreadPriority = thread::internal::Priority< thread::backend::PriorityType, thread::backend::kLowestPriority, thread::backend::kHighestPriority, thread::backend::kDefaultPriority > |
using | Thread = ::pw::thread::Thread |
Enumerations | |
enum class | MultiBufProperty : uint8_t { kConst = 1 << 0 , kLayerable = 1 << 1 , kObservable = 1 << 2 } |
Basic properties of a MultiBuf. More... | |
Functions | |
constexpr size_t | countl_zero (size_t x) noexcept |
constexpr size_t | bit_width (size_t x) noexcept |
constexpr size_t | bit_ceil (size_t x) noexcept |
class pw::Deallocator | DoGetInfo (InfoType info_type, const void *ptr) override |
template<> | |
StatusWithSize | ToString (const async2::ReadyType &, span< char > buffer) |
template<> | |
StatusWithSize | ToString (const async2::PendingType &, span< char > buffer) |
template<typename T > | |
StatusWithSize | ToString (const async2::Poll< T > &poll, span< char > buffer) |
template<> | |
StatusWithSize | ToString (const async2::Poll<> &poll, span< char > buffer) |
bool | IsAlignedAs (const void *ptr, size_t alignment) |
Returns whether the given pointer meets the given alignment requirement. | |
template<typename T > | |
bool | IsAlignedAs (const void *ptr) |
constexpr size_t | AlignDown (uintptr_t value, size_t alignment) |
Returns the value rounded down to the nearest multiple of alignment. | |
template<typename T > | |
constexpr T * | AlignDown (T *value, size_t alignment) |
Returns the value rounded down to the nearest multiple of alignment. | |
constexpr size_t | AlignUp (uintptr_t value, size_t alignment) |
Returns the value rounded up to the nearest multiple of alignment. | |
template<typename T > | |
constexpr T * | AlignUp (T *value, size_t alignment) |
Returns the value rounded up to the nearest multiple of alignment. | |
constexpr size_t | Padding (size_t length, size_t alignment) |
Returns the number of padding bytes required to align the provided length. | |
ByteSpan | GetAlignedSubspan (ByteSpan bytes, size_t alignment) |
constexpr ByteBuilder::iterator | operator+ (int n, ByteBuilder::iterator it) |
template<typename T > | |
span< const std::byte, sizeof(T)> | ObjectAsBytes (const T &obj) |
template<typename T > | |
span< std::byte, sizeof(T)> | ObjectAsWritableBytes (T &obj) |
PW_CONSTEVAL std::byte | operator""_b (unsigned long long value) |
template<typename InputIt , typename Predicate > | |
constexpr bool | all_of (InputIt first, InputIt last, Predicate pred) |
template<typename InputIt , typename Predicate > | |
constexpr bool | any_of (InputIt first, InputIt last, Predicate pred) |
template<typename InputIt , typename Predicate > | |
constexpr InputIt | find_if (InputIt first, InputIt last, Predicate pred) |
template<typename T , size_t kLhsSize, size_t kRhsSize> | |
bool | operator== (const Vector< T, kLhsSize > &lhs, const Vector< T, kRhsSize > &rhs) |
template<typename T , size_t kLhsSize, size_t kRhsSize> | |
bool | operator!= (const Vector< T, kLhsSize > &lhs, const Vector< T, kRhsSize > &rhs) |
template<typename T , size_t kLhsSize, size_t kRhsSize> | |
bool | operator< (const Vector< T, kLhsSize > &lhs, const Vector< T, kRhsSize > &rhs) |
template<typename T , size_t kLhsSize, size_t kRhsSize> | |
bool | operator<= (const Vector< T, kLhsSize > &lhs, const Vector< T, kRhsSize > &rhs) |
template<typename T , size_t kLhsSize, size_t kRhsSize> | |
bool | operator> (const Vector< T, kLhsSize > &lhs, const Vector< T, kRhsSize > &rhs) |
template<typename T , size_t kLhsSize, size_t kRhsSize> | |
bool | operator>= (const Vector< T, kLhsSize > &lhs, const Vector< T, kRhsSize > &rhs) |
template<auto method, typename T > | |
auto | bind_member (T *instance) |
template<typename Function > | |
ScopeGuard (Function()) -> ScopeGuard< Function(*)()> | |
template<typename A , typename B , typename T > | |
constexpr bool | CheckedAdd (A a, B b, T &result) |
template<typename T , typename A , typename B > | |
constexpr std::optional< T > | CheckedAdd (A a, B b) |
template<typename T , typename Inc > | |
constexpr bool | CheckedIncrement (T &base, Inc inc) |
template<typename A , typename B , typename T > | |
constexpr bool | CheckedSub (A a, B b, T &result) |
template<typename T , typename A , typename B > | |
constexpr std::optional< T > | CheckedSub (A a, B b) |
template<typename T , typename Dec > | |
constexpr bool | CheckedDecrement (T &base, Dec dec) |
template<typename A , typename B , typename T > | |
constexpr bool | CheckedMul (A a, B b, T &result) |
template<typename T , typename A , typename B > | |
constexpr std::optional< T > | CheckedMul (A a, B b) |
template<typename T > | |
constexpr T | IntegerDivisionRoundNearest (T dividend, T divisor) |
template<typename T > | |
constexpr T | add_sat (T lhs, T rhs) noexcept |
template<typename T > | |
constexpr T | mul_sat (T lhs, T rhs) noexcept |
template<class ResultT , size_t kSourceExtentBytes> | |
internal::SpanFromBytes< ResultT, kSourceExtentBytes > | span_cast (span< std::byte, kSourceExtentBytes > bytes) |
template<class ResultT , size_t kSourceExtentBytes> | |
internal::SpanFromBytes< const ResultT, kSourceExtentBytes > | span_cast (span< const std::byte, kSourceExtentBytes > bytes) |
constexpr Status | OkStatus () |
constexpr bool | operator== (const Status &lhs, const Status &rhs) |
constexpr bool | operator!= (const Status &lhs, const Status &rhs) |
template<typename T , size_t kLhsCapacity, size_t kRhsCapacity> | |
constexpr bool | operator== (const InlineBasicString< T, kLhsCapacity > &lhs, const InlineBasicString< T, kRhsCapacity > &rhs) noexcept |
template<typename T , size_t kLhsCapacity, size_t kRhsCapacity> | |
constexpr bool | operator!= (const InlineBasicString< T, kLhsCapacity > &lhs, const InlineBasicString< T, kRhsCapacity > &rhs) noexcept |
template<typename T , size_t kLhsCapacity, size_t kRhsCapacity> | |
constexpr bool | operator< (const InlineBasicString< T, kLhsCapacity > &lhs, const InlineBasicString< T, kRhsCapacity > &rhs) noexcept |
template<typename T , size_t kLhsCapacity, size_t kRhsCapacity> | |
constexpr bool | operator<= (const InlineBasicString< T, kLhsCapacity > &lhs, const InlineBasicString< T, kRhsCapacity > &rhs) noexcept |
template<typename T , size_t kLhsCapacity, size_t kRhsCapacity> | |
constexpr bool | operator> (const InlineBasicString< T, kLhsCapacity > &lhs, const InlineBasicString< T, kRhsCapacity > &rhs) noexcept |
template<typename T , size_t kLhsCapacity, size_t kRhsCapacity> | |
constexpr bool | operator>= (const InlineBasicString< T, kLhsCapacity > &lhs, const InlineBasicString< T, kRhsCapacity > &rhs) noexcept |
template<typename T , size_t kLhsCapacity> | |
constexpr bool | operator== (const InlineBasicString< T, kLhsCapacity > &lhs, const T *rhs) |
template<typename T , size_t kRhsCapacity> | |
constexpr bool | operator== (const T *lhs, const InlineBasicString< T, kRhsCapacity > &rhs) |
template<typename T , size_t kLhsCapacity> | |
constexpr bool | operator!= (const InlineBasicString< T, kLhsCapacity > &lhs, const T *rhs) |
template<typename T , size_t kRhsCapacity> | |
constexpr bool | operator!= (const T *lhs, const InlineBasicString< T, kRhsCapacity > &rhs) |
template<typename T , size_t kLhsCapacity> | |
constexpr bool | operator< (const InlineBasicString< T, kLhsCapacity > &lhs, const T *rhs) |
template<typename T , size_t kRhsCapacity> | |
constexpr bool | operator< (const T *lhs, const InlineBasicString< T, kRhsCapacity > &rhs) |
template<typename T , size_t kLhsCapacity> | |
constexpr bool | operator<= (const InlineBasicString< T, kLhsCapacity > &lhs, const T *rhs) |
template<typename T , size_t kRhsCapacity> | |
constexpr bool | operator<= (const T *lhs, const InlineBasicString< T, kRhsCapacity > &rhs) |
template<typename T , size_t kLhsCapacity> | |
constexpr bool | operator> (const InlineBasicString< T, kLhsCapacity > &lhs, const T *rhs) |
template<typename T , size_t kRhsCapacity> | |
constexpr bool | operator> (const T *lhs, const InlineBasicString< T, kRhsCapacity > &rhs) |
template<typename T , size_t kLhsCapacity> | |
constexpr bool | operator>= (const InlineBasicString< T, kLhsCapacity > &lhs, const T *rhs) |
template<typename T , size_t kRhsCapacity> | |
constexpr bool | operator>= (const T *lhs, const InlineBasicString< T, kRhsCapacity > &rhs) |
template<size_t kBufferSize = 0u, typename... Args> | |
auto | MakeString (Args &&... args) |
system::AsyncCore & | System () |
void | SystemStart (channel::ByteReaderWriter &io_channel) |
void | InfiniteLoop () |
Variables | |
constexpr size_t | kExternallyAllocatedThreadStack |
constexpr ConstexprTag | kConstexpr {} |
Provides basic helpers for reading and writing UTF-8 encoded strings.
have no equivalent here.
For template parameter and variable naming, C
indicates the container type to which the function is applied, Pred
indicates the predicate object type to be used by the function and T
indicates the applicable element type.
using pw::InlineAsyncDeque = typedef BasicInlineAsyncDeque<T, uint16_t, kCapacity> |
Async wrapper around BasicInlineDeque.
This class mimics the structure of BasicInlineDequeImpl
to allow referring to an InlineAsyncDeque
without an explicit maximum size.
using pw::InlineAsyncQueue = typedef BasicInlineAsyncQueue<ValueType, uint16_t, kCapacity> |
Async wrapper around BasicInlineQueue.
This class mimics the structure of BasicInlineQueue
to allow referring to an InlineAsyncQueue
without an explicit maximum size.
using pw::InlineDeque = typedef BasicInlineDeque<T, uint16_t, kCapacity> |
The InlineDeque
class is similar to the STL's double ended queue (std::deque
), except it is backed by a fixed-size buffer. InlineDeque
's must be declared with an explicit maximum size (e.g. InlineDeque<int, 10>>
) but deques can be used and referred to without the max size template parameter (e.g. InlineDeque<int>
).
To allow referring to a pw::InlineDeque
without an explicit maximum size, all InlineDeque
classes inherit from a RawStorage
class, which in turn inherits from InlineDeque<T>
, which stores the maximum size in a variable. This allows InlineDeque
s to be used without having to know their maximum size at compile time. It also keeps code size small since function implementations are shared for all maximum sizes.
An InlineDeque
cannot increase its capacity. Any operations that would exceed the capacity (e.g. assign
, push_back
, push_front
) fail a PW_ASSERT
. Avoid this by choosing a large enough capacity or checking full()
before adding items.
using pw::InlineQueue = typedef BasicInlineQueue<T, uint16_t, kCapacity> |
The InlineQueue
class is similar to std::queue<T, std::deque>
, except it is backed by a fixed-size buffer. InlineQueue
's must be declared with an explicit maximum size (e.g. InlineQueue<int, 10>>
) but deques can be used and referred to without the max size template parameter (e.g. InlineQueue<int>
).
pw::InlineQueue
is wrapper around pw::InlineDeque
with a simplified API and push_overwrite()
& emplace_overwrite()
helpers.
using pw::IntrusiveList = typedef containers::future::IntrusiveList<T> |
A doubly-linked intrusive list.
IntrusiveList<T> is a handle to access and manipulate the list, and IntrusiveList<T>::Item is the type from which the base class items must derive.
As a doubly-linked list, operations such as removal are O(1) in time, and the list may be iterated in either direction. However, the overhead needed is 2*sizeof(T*)
.
This class is modeled on std::list
, with the following differences:
iterator
s and not const_iterator
s:erase
is provided that takes a direct reference to an item.T | Type of intrusive items stored in the list. |
using pw::Thread = typedef ::pw::thread::Thread |
pw::thread::Thread
will be renamed to pw::Thread
. New code should refer to pw::Thread
.
using pw::ThreadPriority = typedef thread::internal::Priority<thread::backend::PriorityType, thread::backend::kLowestPriority, thread::backend::kHighestPriority, thread::backend::kDefaultPriority> |
Represents a thread's priority. Schedulers favor higher priority tasks when determining which thread to run. Scheduling policies differ, but a common default policy for real-time operating systems is preemptive scheduling, where the highest priority ready thread is always selected to run. If there are multiple tasks with the same priority, RTOSes may use round-robin scheduling, where each ready thread at a given priority is given equal opportunity to run.
Priorities may be compared with ==
, !=
, <
, etc. Comparisons occur in terms of the native priorities they represent, but are translated such that logically lower priorities always compare as less than higher priorities, even if the underlying RTOS uses lower numbers for higher priorities.
|
strong |
Basic properties of a MultiBuf.
|
constexprnoexcept |
Polyfill of C++26's std::add_sat
. Returns the sum of two integers, giving the integer's maximum or minimum value if the sum would otherwise have overflowed.
For example, add_sat<uint8_t>(250, 6)
returns 255
instead of the overflowed value (0
).
|
constexpr |
Backport of <algorithm>'s constexprt std::all_of()
so it's available in C++17.
|
constexpr |
Backport of <algorithm>'s constexprt std::any_of()
so it's available in C++17.
|
constexpr |
Backport of <algorithm>'s constexprt std::find_if()
so it's available in C++17.
ByteSpan pw::GetAlignedSubspan | ( | ByteSpan | bytes, |
size_t | alignment | ||
) |
Returns the largest aligned subspan of a given byte span.
The subspan will start and end on alignment boundaries.
ByteSpan
within bytes
aligned to alignment
, or an empty ByteSpan
if alignment was not possible.
|
inline |
Loops infinitely. Call as pw_InfiniteLoop()
in C.
Infinite loops without side effects are undefined behavior. Use pw::InfiniteLoop
in place of an empty while (true) {}
or for (;;) {}
.
|
constexpr |
Performs integer division and rounds to the nearest integer. Gives the same result as std::round(static_cast<double>(dividend) / static_cast<double>(divisor))
, but requires no floating point operations and is constexpr
.
embed:rst:leading-asterisk * .. warning:: * * ``signed`` or ``unsigned`` ``int``, ``long``, or ``long long`` operands * overflow if: * * - the quotient is positive and ``dividend + divisor/2`` overflows, or * - the quotient is negative and ``dividend - divisor/2`` overflows. * * To avoid overflow, do not use this function with very large * operands, or cast ``int`` or ``long`` to a larger type first. Overflow * cannot occur with types smaller than ``int`` because C++ implicitly * converts them to ``int``. *
bool pw::IsAlignedAs | ( | const void * | ptr | ) |
Returns whether the given pointer meets the alignment requirement for the given type.
|
constexprnoexcept |
Polyfill of C++26's std::mul_sat
. Returns the product of two integers, giving the integer's maximum or minimum value if the product would otherwise have overflowed.
For example, for 100 * 10 = 1000
, mul_sat<uint8_t>(100, 10)
returns 255
instead of the overflowed value (232
).
span< const std::byte, sizeof(T)> pw::ObjectAsBytes | ( | const T & | obj | ) |
Gets a read-only pw::span<const std::byte>
(ConstByteSpan
) view of an object.
The returned span has a static extent.
span< std::byte, sizeof(T)> pw::ObjectAsWritableBytes | ( | T & | obj | ) |
Gets a writable pw::span<std::byte>
(ByteSpan
) view of an object.
The returned span has a static extent.
|
constexpr |
Returns an
embed:rst:inline :c:enumerator:`OK`
status. Equivalent to Status()
or Status(PW_STATUS_OK)
. This function is used instead of a Status::Ok()
function, which would be too similar to Status::ok()
.
PW_CONSTEVAL std::byte pw::operator""_b | ( | unsigned long long | value | ) |
Returns a std::byte
when used as a _b
suffix.
This is useful for writing byte literals, particularly in tests. To use, add using ::pw::operator""_b;
and then use like 5_b
in order to create a std::byte
with the contents 5
.
This should not be used in header files, as it requires a using
declaration that will be publicly exported at whatever level it is used.
internal::SpanFromBytes< const ResultT, kSourceExtentBytes > pw::span_cast | ( | span< const std::byte, kSourceExtentBytes > | bytes | ) |
Casts a pw::span<const std::byte>
(ConstByteSpan
) to a span of a different const type.
This function is only safe to use if the underlying data is actually of the specified type. You cannot safely use this function to reinterpret e.g. a raw byte array from malloc()
as a span of integers.
This function is essentially the inverse of pw::as_bytes
.
If kSourceExtentBytes
is dynamic_extent
, the returned span also has a dynamic extent. Otherwise, the returned span has a static extent of kSourceExtentBytes / sizeof(ResultT)
.
ResultT | The type of the returned span. Must be one byte to avoid misuse and violation of the strict aliasing rule. This restriction might be lifted in the future. |
kSourceExtentBytes | The extent of the source byte span. This is normally inferred and need not be explicitly provided. |
|
inline |
Returns a reference to the global pw_system instance. pw::System() provides several features for applications: a memory allocator, an async dispatcher, and a RPC server.
void pw::SystemStart | ( | channel::ByteReaderWriter & | io_channel | ) |
Starts running pw_system:async
with the provided IO channel. This function never returns.
|
inlineconstexpr |
Value used to select a constexpr
constructor tagged with pw::ConstexprTag
.
|
inlineconstexpr |