From 8a3df95491f47b1f85d5e38b5f78f31e24ccec65 Mon Sep 17 00:00:00 2001 From: Sasha Koshka Date: Fri, 25 Apr 2025 16:06:17 -0400 Subject: [PATCH] Clarify concurrency in Trans methods --- connection.go | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/connection.go b/connection.go index e1b07c4..05dec8a 100644 --- a/connection.go +++ b/connection.go @@ -28,26 +28,31 @@ type Conn interface { SetSizeLimit(limit int64) } -// Trans is a HOPP transaction. +// Trans is a HOPP transaction. Methods of this interface are not safe for +// concurrent use with the exception of the Close and ID methods. The +// recommended use case is one goroutine per transaction. type Trans interface { // Close closes the transaction. Any blocked operations will be - // unblocked and return errors. + // unblocked and return errors. This method is safe for concurrent use. Close() error // ID returns the transaction ID. This must not change, and it must be - // unique within the connection. + // unique within the connection. This method is safe for concurrent use. ID() int64 // TODO: add methods for setting send and receive deadlines - // Send sends a message. + // Send sends a message. This method is not safe for concurrent use. Send(method uint16, data []byte) error // SendWriter sends data written to an [io.Writer]. Any writer - // previously opened through this function will be discarded. + // previously opened through this function will be discarded. This + // method is not safe for concurrent use, and neither is its result. SendWriter(method uint16) (io.Writer, error) - // Receive receives a message. + // Receive receives a message. This method is not safe for concurrent + // use. Receive() (method uint16, data []byte, err error) // ReceiveReader receives a message as an [io.Reader]. Any reader - // previously opened through this function will be discarded. + // previously opened through this function will be discarded. This + // method is not safe for concurrent use, and neither is its result. ReceiveReader() (method uint16, data io.Reader, err error) }