salmanoff/include/adapters/README.md

Adapter Awaiters

This directory contains coroutine/awaitable adapters that wrap callback-driven or event-driven APIs.

Placement rules

• Put wrappers for external APIs in provider-specific subdirectories.
  • Examples: boostAsio/, opencl/, liburing/.
• Put wrappers for SMO/internal APIs in smo/.
• Do not place adapter awaiters in feature folders like stimBuffApis/* or smocore/* unless they are strictly private to one translation unit.

Tree layout

include/adapters/
  README.md
  boostAsio/
    <boost asio adapter awaiters>
  opencl/
    <OpenCL adapter awaiters>
  smo/
    cpsCallbackAReq.h
    livoxProto1CpsAwaiters.h
    <other SMO/internal callback adapters>

Design guidelines

• Name adapter awaiter wrapper functions get<fnName>AReqAwaiter(), where <fnName> is the wrapped CPS/API request symbol with its library prefix removed and each _-delimited segment Pascal-cased (e.g. livoxProto1_getOrCreateDeviceReq → getGetOrCreateDeviceReqAReqAwaiter()).
• Keep adapters small and single-purpose; but unify where possible to reduce code duplication.
• Make result types explicit for multi-argument callbacks.
• Resume coroutines on a caller-specified executor/io_service.
• Avoid embedding business logic in adapters.