Skip to content

docs: clarify lifetime and ownership rules for C hook callback parameters#522

Merged
kinyoklion merged 3 commits intomainfrom
rlamb/sdk-2173/elaborate-hook-data-lifetimes
Apr 15, 2026
Merged

docs: clarify lifetime and ownership rules for C hook callback parameters#522
kinyoklion merged 3 commits intomainfrom
rlamb/sdk-2173/elaborate-hook-data-lifetimes

Conversation

@kinyoklion
Copy link
Copy Markdown
Member

@kinyoklion kinyoklion commented Apr 13, 2026

Strengthen the documentation in hook.h to make it explicit that all SDK-provided pointers (series_context, data, detail, etc.) must not be retained, cached, or stored beyond the scope of the callback invocation, and that any data needed outside the callback must be copied.


Note

Low Risk
Documentation-only updates that clarify ownership/lifetime rules for SDK-provided callback parameters; no runtime behavior changes.

Overview
Adds explicit lifetime/ownership warnings to the C hook API docs (hook.h), stating that all SDK-provided pointers (series_context, data, detail, etc.) are temporary and must not be retained beyond the callback.

Tightens the per-callback LIFETIME/RETURNS sections to consistently note that any needed data must be copied within the callback and that returned EvaluationSeriesData ownership transfers to the SDK.

Reviewed by Cursor Bugbot for commit 8fb08ab. Bugbot is set up for automated code reviews on this repo. Configure here.

Strengthen the documentation in hook.h to make it explicit that all
SDK-provided pointers (series_context, data, detail, etc.) must not be
retained, cached, or stored beyond the scope of the callback invocation,
and that any data needed outside the callback must be copied.
@kinyoklion kinyoklion requested a review from a team as a code owner April 13, 2026 22:29
Copy link
Copy Markdown
Contributor

@beekld beekld left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm curious to hear what prompted the extra warning, but always a good reminder.

LGTM

@kinyoklion kinyoklion changed the title doc: clarify lifetime and ownership rules for C hook callback parameters docs: clarify lifetime and ownership rules for C hook callback parameters Apr 14, 2026
@kinyoklion kinyoklion merged commit 1c85d89 into main Apr 15, 2026
44 of 46 checks passed
@kinyoklion kinyoklion deleted the rlamb/sdk-2173/elaborate-hook-data-lifetimes branch April 15, 2026 15:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants