Skip to content

docs: clarify UnmarshalMsg input and receiver storage - #458

Closed
ViktorBystrov72 wants to merge 1 commit into
tinylib:masterfrom
ViktorBystrov72:docs/unmarshal-storage
Closed

ViktorBystrov72 wants to merge 1 commit into
tinylib:masterfrom
ViktorBystrov72:docs/unmarshal-storage

Conversation

@ViktorBystrov72

Copy link
Copy Markdown

Clarify the distinction between the encoded input buffer and reusable storage in generated UnmarshalMsg receivers. Input with equal length and capacity is sufficient; adding spare input capacity does not prevent allocations in decoded fields. Document the returned suffix for concatenated objects and the limits of receiver reuse, including string and slice-growth allocations.

This expands the public interface GoDoc in response to #154. It does not change decoding behavior or the separately maintained wiki.

Validation: make prepare, package race tests and vet passed. A separate probe using freshly generated methods decoded concatenated objects with len(input) == cap(input) and verified that a preallocated receiver retained its slice backing arrays across calls. The rendered GoDoc was checked with go doc.

Refs #154.

Signed-off-by: Виктор Быстров <anatema@bk.ru>

@klauspost klauspost left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Seems like extra fluff with no value.

Comment thread msgp/read.go
Comment on lines +99 to +101
// Generated methods read encoded data from the input slice's length. They do not
// use spare capacity in that slice as scratch space; an input slice with equal
// length and capacity is sufficient.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This seems to expand the requirements of the interface. While it may hold (and surely is good practice) the details are left to the implementer.

I honestly don't see a need to specify this.

Comment thread msgp/read.go
Comment on lines +103 to +107
// Generated methods can reuse storage in the receiver, such as existing slice
// capacity and maps. Reusing the receiver across calls can therefore reduce
// allocations. Extra capacity in the input slice does not provide this benefit.
// Decoding can still allocate, for example when growing receiver slices or
// reading strings with [ReadStringBytes].

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This also seems unnecesary.

@klauspost
klauspost requested a review from philhofer November 13, 2026 09:10
@ViktorBystrov72

Copy link
Copy Markdown
Author

Thanks for the review. The wording overstates the interface contract, and removing the rejected paragraphs leaves no useful change. Withdrawing this PR.

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