From 1629551c5e42d7f6089547f84e552b30ed6da31f Mon Sep 17 00:00:00 2001 From: Leonid Emar-Kar Date: Tue, 4 Jun 2024 12:32:01 +0100 Subject: [PATCH 1/2] update ReadFrom and ReadFromWithConcurrency docs --- client.go | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/client.go b/client.go index dd037597..0b3cbe0c 100644 --- a/client.go +++ b/client.go @@ -1756,6 +1756,8 @@ func (f *File) writeAt(b []byte, off int64) (written int, err error) { // Giving a concurrency of less than one will default to the Client’s max concurrency. // // Otherwise, the given concurrency will be capped by the Client's max concurrency. +// +// This method is preferred over calling ReadFrom to guarantee concurrent reads/writes. func (f *File) ReadFromWithConcurrency(r io.Reader, concurrency int) (read int64, err error) { f.mu.Lock() defer f.mu.Unlock() @@ -1916,6 +1918,17 @@ func (f *File) readFromWithConcurrency(r io.Reader, concurrency int) (read int64 // This method is preferred over calling Write multiple times // to maximise throughput for transferring the entire file, // especially over high-latency links. +// +// If client uses concurrent writes, given r needs to implement one of the interfaces: +// +// Len() int +// Size() int64 +// Stat() (os.FileInfo, error) +// +// or be an instance of [io.LimitedReader] to determine the number of possible +// concurrent requests. Otherwise, reads/writes are performed in nonparallel, sliced +// in chunks with the max packet size. ReadFromWithConcurrency explicit call can +// guarantee concurrent processing of the reader. func (f *File) ReadFrom(r io.Reader) (int64, error) { f.mu.Lock() defer f.mu.Unlock() From 1988803cae971a0b6de1fa23f227718b88ede7b2 Mon Sep 17 00:00:00 2001 From: Leonid Emar-Kar Date: Wed, 5 Jun 2024 10:53:34 +0100 Subject: [PATCH 2/2] update docs with suggested improvements --- client.go | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/client.go b/client.go index 0b3cbe0c..83047d0a 100644 --- a/client.go +++ b/client.go @@ -1757,7 +1757,8 @@ func (f *File) writeAt(b []byte, off int64) (written int, err error) { // // Otherwise, the given concurrency will be capped by the Client's max concurrency. // -// This method is preferred over calling ReadFrom to guarantee concurrent reads/writes. +// When one needs to guarantee concurrent reads/writes, this method is preferred +// over ReadFrom. func (f *File) ReadFromWithConcurrency(r io.Reader, concurrency int) (read int64, err error) { f.mu.Lock() defer f.mu.Unlock() @@ -1919,16 +1920,17 @@ func (f *File) readFromWithConcurrency(r io.Reader, concurrency int) (read int64 // to maximise throughput for transferring the entire file, // especially over high-latency links. // -// If client uses concurrent writes, given r needs to implement one of the interfaces: +// To ensure concurrent writes, the given r needs to implement one of +// the following receiver methods: // // Len() int // Size() int64 // Stat() (os.FileInfo, error) // // or be an instance of [io.LimitedReader] to determine the number of possible -// concurrent requests. Otherwise, reads/writes are performed in nonparallel, sliced -// in chunks with the max packet size. ReadFromWithConcurrency explicit call can -// guarantee concurrent processing of the reader. +// concurrent requests. Otherwise, reads/writes are performed sequentially. +// ReadFromWithConcurrency can be used explicitly to guarantee concurrent +// processing of the reader. func (f *File) ReadFrom(r io.Reader) (int64, error) { f.mu.Lock() defer f.mu.Unlock()