golang/go

net: document PacketConn IO operations in relation to packet sizes

Open

#18,056 opened on Nov 26, 2016

View on GitHub
 (2 comments) (6 reactions) (0 assignees)Go (19,008 forks)batch import
DocumentationNeedsFixhelp wanted

Repository metrics

Stars
 (133,883 stars)
PR merge metrics
 (No merged PRs in 30d)

Description

The current phrasing on PacketConn.ReadFrom and PacketConn.WriteTo is:

ReadFrom reads a packet from the connection, copying the payload into b. It returns the number of bytes copied into b and the return address that was on the packet. ReadFrom can be made to time out and return an Error with Timeout() == true after a fixed time limit; see SetDeadline and SetReadDeadline.

and

WriteTo writes a packet with payload b to addr. WriteTo can be made to time out and return an Error with Timeout() == true after a fixed time limit; see SetDeadline and SetWriteDeadline. On packet-oriented connections, write timeouts are rare.

What is the expected behavior of ReadFrom when the buffer provided is not large enough to read the entire packet? Does the remaining payload get dropped? Does the next call to ReadFrom finish off the packet?

On the flip-side, what happens when the buffer provided to WriteTo is larger than the MTU. Should the method implicitly chunk the input into multiple packet-sized chunks?

\cc @mikioh

Contributor guide

Research direction
Check the Go net package documentation and source code to determine the behavior of PacketConn.ReadFrom when the buffer is too small (truncation) and WriteTo when the buffer exceeds MTU (expected to fail or not). Clarify these behaviors in the documentation.
Tech stack
go
Domain
backend
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Under 1 hour
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
Go
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
80