Add narrow Struct builder C API - #1153
Conversation
Merging this PR will not alter performance
Comparing 
Footnotes
|
ofek
left a comment
There was a problem hiding this comment.
Please provide a concrete example of code that illustrates how you intend for this to be used.
| * This header exposes no msgspec object layouts. The capsule table is an | ||
| * opaque, versioned capability boundary implemented by msgspec. | ||
| */ | ||
| #define MSGSPEC_CAPI_CAPSULE_NAME "msgspec._core._C_API_v1" |
There was a problem hiding this comment.
I really do not believe a _v1 is needed in this naming and it confuses me quite a bit. You have the right approach was we can slowly add more things in when this first PR has been merged but a recommendation I have is to remove this _v1 it isn't needed here.
| * failure. The caller must treat every entry as moved after the call. | ||
| * - success returns a new reference; failure returns NULL with an exception. | ||
| */ | ||
| typedef struct Msgspec_CAPI_v1 { |
There was a problem hiding this comment.
More or a less a ditto to what I explained a bit earlier.
There was a problem hiding this comment.
@goblinmode2700 while I love your approach to this just know that I stopped working on #958 due to my IRL job taking up more chunks of my time away and wanting to explore and invent new things. I am however willing to take the time to review and help you this this PR.
Be sure to comment that it closes #958 Just know that I am not inline with the whole _v1 thing and believe this suffix needs dropping. As long as you provide some code examples you should be all set to go.
What this draft tests
This is a deliberately narrow alternative/complement to #961: one opaque,
versioned C-API capability for constructing an already-validated
msgspec.Structfrom declared-order owned references. It does not expose msgspec's private
layouts, offsets, metaclass construction, encoders, or decoders.
The concrete consumer is a native TOON decoder. Its parser already knows the
target schema and has final Python field values, but today it must call the
public Struct constructor, which repeats argument binding. The proposed call
lets msgspec retain ownership of allocation, defaults/factories, GC decisions,
abstract checks, and
__post_init__while removing that duplicate binding work.Safety and fallback
handle.
class cycle found during external review.
contract.
fallback status without an exception.
Evidence
S1 about 3% faster (resolved only after doubled sampling), S6 about 3% faster
but unresolved on confirmation, and S12 about 5% faster and resolved.
This is a draft to discuss whether this small producer-owned capability is a
maintainable first C-API boundary. Production
msgspec-toonremains pinned tostock
msgspec==0.21.1; no patched dependency is shipped.Thank you to @Vizonex and the participants in #958/#961 for establishing the
capsule/test-module prior art and surfacing the broader extension use cases.