C and C++ interface¶

C and C++ code reaches a box through two headers that come with the sharedbox wheel, in the folder that get_include returns. This page says where each one is specified; to get started, follow How to accept a box in a C++ extension instead.

Header	What it declares	Specified in
`sharedbox/sharedbox.hpp`	the C++20 API: `sharedbox::handle`, `sharedbox::result`, `sharedbox::status`, `sharedbox::type_view` and the `encode_` and `decode_` functions of the value types; the inline namespace is `v2`	`sharedbox.hpp`
`sharedbox/sharedbox_c.h`	the `sbx_*` C functions, including `sbx_field_desc` and the typed reads and writes, and the status codes	`sharedbox_c.h`
both	`sbx_handle`, the struct a capsule holds	Capsule handle

The Python side of the exchange, __sharedbox_box__ and the capsule it returns, is specified in The PyCapsule interface. The CMake targets are in Build and packaging.

Thread safety¶

Which calls you may make from several threads on one handle is the same whether you use sharedbox::handle or an sbx_handle with the C functions. The rules are listed in sharedbox.hpp.

Errors¶

Implementation language: sharedbox::result<T>, which every C++ call that can fail returns, and the C++20 and C++23 build rules that come with it
sharedbox.hpp: what each sharedbox::status means, including status::os
sharedbox_c.h: the SBX_OK and SBX_E_* codes the C functions return