Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Update all uses of "_out" functions to inform caller of required buffer size when passed buffer is too small

Đang mở
  • Có gì không ổn?
#163 2 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 2 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
25/100
Loại issue
Tính năng
Độ rõ ràng
Cần làm rõ
Mức độ hoạt động
Sôi nổi
Công nghệ
rust
Lĩnh vực
cryptography

Hướng nghiên cứu

Start by inventorying every _out and _final function in the repository and reading the existing error and buffer-handling conventions. Use the memory benches and compiled-assembly checks mentioned in the issue to assess returning Self from _final functions. Done means consistent recoverable buffer-too-small behavior, idempotent failures, and updated documentation across all affected APIs.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

There is not currently a consistent way for a caller of an "_out" function (any function that writes its output into a caller-passed buffer argument) to determine the required size for the buffer, or to communicate an error back to the caller in a recoverable way.

The initial proposal here is, when the passed buffer is too small, all "_out" functions should return a "buffer too small" error enum, which includes the actual required size for the buffer for a retry of this API to succeed.

Using this pattern:

  1. allows callers mistakenly passing too small of a buffer to be given sufficient information to try again with a correctly-sized one
  2. allows callers wanting to check the size immediately to pass a zero-length buffer to trigger the same behaviour
  3. eliminates the need for an additional "_out_len()" function, taking identical parameters, whose sole purpose is to fulfill point 2

An edge case that needs to be examined is "_final" functions, which consume the called object. In this case, the caller would not be able to either probe the correct length, or retry for a failed attempt, without losing the object. The proposal here is for all final(self, ..) functions to return -> Result<, (SomeError, Self)>; ie return a tuple containing the error code and a clone of self. This would allow for error recovery on _final() APIs more broadly that only the "buffer too small" case, but it would be best to do some testing with the memory benches and/or Claude to check compiled assembly to see whether this would create an additional burden on the stack.

In addition, some functions may currently silently truncate the output when the provided output buffer is too small (e.g., Hash). My current thinking on this is that they should both provide the truncated output AND return an error indicating the output buffer was too small (using the new pattern). In the case that the caller was intending truncation, they can safely ignore the buffer error, and in the case that truncation was unexpected the caller will be made aware of the error. An alternative would be to decide that the truncation is just a bad idea and have Hash always return the full-length output, and the user can truncate afterwards if they so desire.

Note on implementation - ideally, all functions should return as early as possible on buffer-too-small. This avoids doing unnecessary work before returning, and (hopefully) avoids changes to object state that would need to be unwound before returning the error.

Acceptance Criteria:

  • check whether returning self in "_final" functions will consume additional stack memory, or cause any other unforeseen issues (if so, let's discuss here)
  • apply a consistent pattern for all "_out" functions in the repo
  • apply a consistent pattern for all "_final" functions in the repo
  • any buffer-too-small condition (whether as an error or as a zero-length check) is idempotent (ie does not change the object's state)
  • ensure all documentation is updated to reflect this behaviour
Ngôn ngữ chính
Rust
Star
25
Fork
18
Merge trung bình
14 ngày 10 giờ
Pull request đã merge (30 ngày)
5

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của bcgit/bc-rust

Tất cả issue của bcgit/bc-rust

Issue tương tự

Thêm issue về Rust

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.