 |
C/C++ API Reference
|
Namespaces | |
| namespace | pw |
| The Pigweed namespace. | |
Macros | |
| #define | PW_RPC_COMPLETION_REQUEST_CALLBACK 0 |
| #define | PW_RPC_METHOD_STORES_TYPE 0 |
| #define | PW_RPC_NANOPB_STRUCT_MIN_BUFFER_SIZE 64 |
| #define | PW_RPC_USE_GLOBAL_MUTEX 1 |
| #define | PW_RPC_YIELD_MODE PW_RPC_YIELD_MODE_SLEEP |
| #define | PW_RPC_YIELD_MODE_BUSY_LOOP 100 |
| #define | PW_RPC_YIELD_MODE_SLEEP 101 |
| #define | PW_RPC_YIELD_MODE_YIELD 102 |
| #define | PW_RPC_YIELD_SLEEP_DURATION pw::chrono::SystemClock::duration(1) |
| #define | PW_RPC_CALLBACK_TIMEOUT_TICKS 10000 |
| #define | PW_RPC_DYNAMIC_ALLOCATION 0 |
| #define | PW_RPC_DYNAMIC_CONTAINER(type) std::vector<type> |
| #define | PW_RPC_DYNAMIC_CONTAINER_INCLUDE <vector> |
| #define | PW_RPC_MAKE_UNIQUE_PTR(type, ...) std::unique_ptr<type>(new type(__VA_ARGS__)) |
| #define | PW_RPC_MAKE_UNIQUE_PTR_INCLUDE <memory> |
| #define | PW_RPC_ENCODING_BUFFER_SIZE_BYTES 512 |
| #define | PW_RPC_CONFIG_LOG_LEVEL PW_LOG_LEVEL_INFO |
| The log level to use for this module. Logs below this level are omitted. | |
| #define | PW_RPC_CONFIG_LOG_MODULE_NAME "PW_RPC" |
| The log module name to use for this module. | |
| #define | PW_RPC_NANOPB_STRUCT_BUFFER_STACK_ALLOCATE 1 |
| #define | _PW_RPC_NANOPB_STRUCT_STORAGE_CLASS |
| Internal macro for declaring the Nanopb struct; do not use. | |
| #define PW_RPC_CALLBACK_TIMEOUT_TICKS 10000 |
pw_rpc call objects wait for their callbacks to complete before they are moved or destoyed. Deadlocks occur if a callback:
If PW_RPC_CALLBACK_TIMEOUT_TICKS is greater than 0, then PW_CRASH is invoked if a thread waits for an RPC callback to complete for more than the specified tick count.
A "tick" in this context is one iteration of a loop that yields releases the RPC lock and yields the thread according to
embed:rst:inline :c:macro:`PW_RPC_YIELD_MODE`
. By default, the thread yields with a 1-tick call to
embed:rst:inline :cpp:func:`pw::this_thread::sleep_for()`
.
| #define PW_RPC_COMPLETION_REQUEST_CALLBACK 0 |
pw_rpc clients may request call completion by sending CLIENT_REQUEST_COMPLETION packet. For client streaming or bi-direction RPCs, this also indicates that the client is done sending requests. While this can be useful in some circumstances, it is often not necessary.
This option controls whether or not include a callback that is called when the client stream requests for completion. The callback is included in all ServerReader/Writer objects as a
embed:rst:inline :cpp:type:`pw::Function`
, so may have a significant cost.
This is disabled by default.
| #define PW_RPC_DYNAMIC_ALLOCATION 0 |
Whether pw_rpc should use dynamic memory allocation internally. If enabled, pw_rpc dynamically allocates channels and its encoding buffer. RPC users may use dynamic allocation independently of this option (e.g. to allocate pw_rpc call objects).
The semantics for allocating and initializing channels change depending on this option. If dynamic allocation is disabled, pw_rpc endpoints (servers or clients) use an externally-allocated, fixed-size array of channels. That array must include unassigned channels or existing channels must be closed to add new channels.
If dynamic allocation is enabled, an span of channels may be passed to the endpoint at construction, but these channels are only used to initialize its internal channels container. External channel objects are NOT used by the endpoint and cannot be updated if dynamic allocation is enabled. No unassigned channels should be passed to the endpoint; they will be ignored. Any number of channels may be added to the endpoint, without closing existing channels, but adding channels will use more memory.
| #define PW_RPC_DYNAMIC_CONTAINER | ( | type | ) | std::vector<type> |
If
embed:rst:inline :c:macro:`PW_RPC_DYNAMIC_ALLOCATION`
is enabled, this macro must expand to a container capable of storing objects of the provided type. This container will be used internally by pw_rpc to allocate the channels list and encoding buffer. Defaults to std::vector<type>, but may be set to any type that supports the following std::vector operations:
emplace_back()pop_back()back()resize()clear()begin(), end()) | #define PW_RPC_DYNAMIC_CONTAINER_INCLUDE <vector> |
If
embed:rst:inline :c:macro:`PW_RPC_DYNAMIC_ALLOCATION`
is enabled, this header file is included in files that use
embed:rst:inline :c:macro:`PW_RPC_DYNAMIC_CONTAINER`
. Defaults to <vector>, but may be set in conjunction with
embed:rst:inline :c:macro:`PW_RPC_DYNAMIC_CONTAINER`
to use a different container type for dynamic allocations in pw_rpc.
| #define PW_RPC_ENCODING_BUFFER_SIZE_BYTES 512 |
Size of the global RPC packet encoding buffer in bytes.
When dynamic allocation is enabled, the encoding buffer is allocated on demand. PW_RPC_ENCODING_BUFFER_SIZE_BYTES serves as a hint for the maximum packet size and for pw::rpc::MaxSafePayloadSize(). It is also used by test helpers that allocate RPC encoding buffers.
| #define PW_RPC_MAKE_UNIQUE_PTR | ( | type, | |
| ... | |||
| ) | std::unique_ptr<type>(new type(__VA_ARGS__)) |
If
embed:rst:inline :c:macro:`PW_RPC_DYNAMIC_ALLOCATION`
is enabled, this macro must expand to a statement that creates a std::unique_ptr-like smart pointer.
| type | The type of the object to construct (e.g. with new) |
| ... | Arguments to pass to the constructor, if any |
| #define PW_RPC_MAKE_UNIQUE_PTR_INCLUDE <memory> |
If
embed:rst:inline :c:macro:`PW_RPC_DYNAMIC_ALLOCATION`
is enabled, this header file is included in files that use
embed:rst:inline :c:macro:`PW_RPC_MAKE_UNIQUE_PTR`
. Defaults to <memory> for std::make_unique.
| #define PW_RPC_METHOD_STORES_TYPE 0 |
pw_rpc Method's can include their MethodType as a runtime accessible variable.
This isn't needed for most applications so is disabled by default.
| #define PW_RPC_NANOPB_STRUCT_BUFFER_STACK_ALLOCATE 1 |
This option determines whether to allocate the Nanopb structs on the stack or in a global variable. Globally allocated structs are NOT thread safe, but work fine when the RPC server's ProcessPacket function is only called from one thread.
| #define PW_RPC_NANOPB_STRUCT_MIN_BUFFER_SIZE 64 |
The Nanopb-based pw_rpc implementation allocates memory to use for Nanopb structs for the request and response protobufs. The template function that allocates these structs rounds struct sizes up to this value so that different structs can be allocated with the same function. Structs with sizes larger than this value cause an extra function to be created, which slightly increases code size.
Ideally, this value will be set to the size of the largest Nanopb struct used as an RPC request or response. The buffer can be stack or globally allocated (see
embed:rst:inline :c:macro:`PW_RPC_NANOPB_STRUCT_BUFFER_STACK_ALLOCATE`
).
This defaults to 64 bytes.
| #define PW_RPC_USE_GLOBAL_MUTEX 1 |
Enable global synchronization for RPC calls. If this is set, a backend must be configured for pw_sync:mutex.
This is enabled by default.
Note: The dependencies of pw_rpc depend on the value of PW_RPC_USE_GLOBAL_MUTEX. When building pw_rpc with Bazel, you should NOT set this module config value directly. Instead, tell the build system which value you wish to select by adding one of the following constraint_values to the target platform:
@pigweed//pw_rpc:use_global_mutex_true (the default)@pigweed//pw_rpc:use_global_mutex_false | #define PW_RPC_YIELD_MODE PW_RPC_YIELD_MODE_SLEEP |
pw_rpc must yield the current thread when waiting for a callback to complete in a different thread. PW_RPC_YIELD_MODE determines how to yield. There are three supported settings:
embed:rst:inline :c:macro:`PW_RPC_YIELD_MODE_BUSY_LOOP`- Do nothing. Release and reacquire the RPC lock in a busy loop.
embed:rst:inline :c:macro:`PW_RPC_USE_GLOBAL_MUTEX`must be 0.
embed:rst:inline :c:macro:`PW_RPC_YIELD_MODE_SLEEP`- Yield with 1-tick calls to
embed:rst:inline :cpp:func:`pw::this_thread::sleep_for()`. A backend must be configured for pw_thread:sleep.
embed:rst:inline :c:macro:`PW_RPC_YIELD_MODE_YIELD`- Yield with
embed:rst:inline :cpp:func:`pw::this_thread::yield()`. A backend must be configured for pw_thread:yield. IMPORTANT: On some platforms,
embed:rst:inline :cpp:func:`pw::this_thread::yield()`does not yield to lower priority tasks and should not be used here.
Note: The dependencies of pw_rpc depend on the value of PW_RPC_YIELD_MODE. When building pw_rpc with Bazel, you should NOT set this module config value directly. Instead, tell the build system which value you wish to select by adding one of the following constraint_values to the target platform:
@pigweed//pw_rpc:yield_mode_busy_loop@pigweed//pw_rpc:yield_mode_busy_sleep (the default)@pigweed//pw_rpc:yield_mode_busy_yield | #define PW_RPC_YIELD_MODE_YIELD 102 |
Supported configuration values for
embed:rst:inline :c:macro:`PW_RPC_YIELD_MODE`
.
| #define PW_RPC_YIELD_SLEEP_DURATION pw::chrono::SystemClock::duration(1) |
If PW_RPC_YIELD_MODE == PW_RPC_YIELD_MODE_SLEEP, PW_RPC_YIELD_SLEEP_DURATION sets how long to sleep during each iteration of the yield loop. The value must be a constant expression that converts to a
embed:rst:inline :cpp:type:`pw::chrono::SystemClock::duration`
.
1.9.6