C/C++ API usage guidelines

C++17 projects should include revo3/revo3.hpp and use revo3::Manager, revo3::Hand, and RAII. Pure C and foreign-language bindings use revo3-sdk.h. Obtain headers, shared libraries, and API documentation from the same official C/C++ SDK package.

C++ lifecycle and ownership

• Manager and Hand are move-only. Do not copy handles or use a source object after moving from it.
• Prefer scope-based RAII cleanup; call close() when a connection must end before the owner leaves scope.
• Subscriptions, MotionHandle, and ServoSession objects have independent lifecycles and must end before their owning application state is destroyed.
• After a disconnect, close old objects and reconnect. Do not reuse motion handles, subscriptions, or sessions created by the old connection.
• Order object lifetimes to prevent background callbacks from accessing application state that has already been destroyed.

See quickstart.cpp for the base RAII structure and multi_hand.cpp for multi-device ownership.

Timeouts, errors, and recovery

• Express durations and timeouts with std::chrono, not unitless magic numbers.
• A returned MotionHandle does not mean motion is complete. Use a bounded wait and handle cancellation and non-completed states.
• Catch revo3::SdkError and record its code, operation effect, and recovery requirement; do not decide retries from what() text alone.
• After a timeout or Indeterminate result, read State and Health before repeating a write operation.
• After reconnecting, reacquire device information and joint layout, then repeat health preflight checks.

See mit_plan.cpp for motion waiting and errors and recovery for recovery rules.

Concurrency and real-time control

• Assign one motion-control owner per hand. Do not concurrently combine discrete motion, Servo, teaching, and replay.
• Send high-rate targets through ServoSession with an explicit cadence, command timeout, and shutdown path.
• Keep long blocking work out of subscription callbacks and data-processing paths; move it to a bounded application queue or worker thread.
• Synchronize shared application state and close callback sources before destroying the state they reference.
• Do not assume application thread scheduling equals the bus rate or firmware sample rate.

See streaming_control.cpp for continuous control and subscriptions.cpp for subscription handling.

C ABI resources and callbacks

• Match every successful create call with its release function and provide one cleanup path for success and failure cases.
• Callback pointers are valid only for the lifetime documented in the header. Copy required fields before retaining them asynchronously or across threads.
• Unregister or close the callback source before releasing its context to avoid dangling access.
• Follow SDK header definitions for C struct layout and ownership of strings, arrays, and error objects.
• Check every returned status, use the revo3_ public-symbol prefix, and never mix Header and shared-library versions.

See discover_devices.cpp for discovery and cleanup flow.