rwc

README

This package provides a ReadWriteCloser that can be reset, in that you are able to switch the underlying io.ReadWriteCloser you are using, without disrupting the application using the ResReadWriteCloser provided in this package.

There are a couple exceptions to this rule. Since Read and Write calls can be blocking, if the ResReadWriteCloser is reset during such operations, it will return ErrRWCReset in place of any error, nil or otherwise, returned by the prior ReadWriteCloser. The original number of bytes read or written are not discarded.

See the package documentation for full docs.

Documentation

Overview

Package rwc provides a resettable ReadWriteCloser, which can change its ReadWriteCloser via a call to the Reset function. Ideally, this should only be done when there are no reads or writes occurring, but it should be thread safe with proper use of a sync.Mutex and an atomic counter.

Index

• Variables
• type ResReadWriteCloser
  • func NewResReadWriteCloser(rwc io.ReadWriteCloser) *ResReadWriteCloser
  • func (r *ResReadWriteCloser) Close() error
  • func (r *ResReadWriteCloser) RWC() io.ReadWriteCloser
  • func (r *ResReadWriteCloser) Read(p []byte) (int, error)
  • func (r *ResReadWriteCloser) Reset(newRWC io.ReadWriteCloser, closeOld bool) error
  • func (r *ResReadWriteCloser) ResetCount() uint64
  • func (r *ResReadWriteCloser) Write(p []byte) (int, error)

Variables

var (
	// ErrEqual is returned if attempting to reset ResReadWriteCloser
	// with a value equal to that which already exists.
	ErrEqual = errors.New("new ReadWriteCloser equal to old ReadWriteCloser")
	// ErrEqualToSelf is returned if attempting to reset ResReadWriteCloser
	// with a value equal to itself.
	ErrEqualToSelf = errors.New("new ReadWriteCloser equal to current ResReadWriteCloser")
	// ErrResetNil is returned if attempting to reset ResReadWriteCloser with a nil value.
	ErrResetNil = errors.New("nil reset not permitted")
	// ErrRWCReset is returned by Read and Write functions on ResReadWriteCloser
	// if it is reset during a read or write.
	ErrRWCReset = errors.New("ReadWriteCloser reset")
)

Types

type ResReadWriteCloser

type ResReadWriteCloser struct {
	// contains filtered or unexported fields
}

ResReadWriteCloser is a ReadWriteCloser who's io.ReadWriteCloser can be safely reset. It implements the io.ReadWriteCloser interface.

If its io.ReadWriteCloser is reset during a read or write operation, the read or write operation will complete on the old connection unless the old connection is closed.

If the io.ReadWriteCloser is reset during a read or write call, ErrRWCReset is returned along with the number of bytes read or written by the old reader. Callers of Read or Write should check for the presence of ErrRWCReset, and if desired, try their calls again. Callers should also check the number of bytes read or written on the old io.ReadWriteCloser after the reset occurred.

func NewResReadWriteCloser

func NewResReadWriteCloser(rwc io.ReadWriteCloser) *ResReadWriteCloser

NewResReadWriteCloser creates a resettable ReadWriteCloser implementing the io.ReadWriteCloser interface. If you attempt to create it with a nil value, a runtime panic will occur. This is done as soon as possible, as the io.ReadWriteCloser used should never be nil, or it will panic during any calls to Read, Write, or Close.

func (*ResReadWriteCloser) Close

func (r *ResReadWriteCloser) Close() error

Close implements the io.Closer interface. It closes the io.ReadWriteCloser assigned under a read mutex lock to ensure a reset cannot occur until all read locks are released. Whether or not to use the ResReadWriteCloser after close is left up to the caller. It can be reset after Close is called.

func (*ResReadWriteCloser) RWC

func (r *ResReadWriteCloser) RWC() io.ReadWriteCloser

RWC returns the underlying io.ReadWriteCloser. If you initialized the ResReadWriteCloser with something like a net.Conn or os.File, you can retrieve the original value via type assertion.

func (*ResReadWriteCloser) Read

func (r *ResReadWriteCloser) Read(p []byte) (int, error)

Read implements the io.Reader interface. If the ReadWriteCloser is reset during a read, ErrRWCReset is returned along with the number of bytes read from the previous ReadWriteCloser. Any error returned by the io.ReadWriteCloser after the reset is replaced with ErrRWCReset. If it is reset before the read takes place, 0 is returned along with ErrRWCReset.

func (*ResReadWriteCloser) Reset

func (r *ResReadWriteCloser) Reset(newRWC io.ReadWriteCloser, closeOld bool) error

Reset will allow you to reset the current io.ReadWriteCloser with a new io.ReadWriteCloser. Ideally, this should only be done when there are no reads or writes occurring.

You cannot reset it with nil, ErrResetNil will be returned. You cannot reset it with a value equal to the existing io.ReadWriteCloser interface, ErrEqual will be returned. You cannot reset it to its own ResReadWriteCloser, ErrEqualToSelf will be returned.

If you set closeOld to true, the old io.ReadWriteCloser will be closed during the reset. Setting closeOld to false could prove useful in certain situations, such as resetting the ResReadWriteCloser with a custom ReadWriteCloser implementation wrapping the one you originally used on creation.

func (*ResReadWriteCloser) ResetCount

func (r *ResReadWriteCloser) ResetCount() uint64

ResetCount returns the number of times the ResReadWriteCloser has been reset. This could be useful for debugging, testing, or if you chose to set up your own limits for resets.

func (*ResReadWriteCloser) Write

func (r *ResReadWriteCloser) Write(p []byte) (int, error)

Write implements the io.Writer interface. If the ReadWriteCloser is reset during a write, ErrRWCReset is returned along with the number of bytes written to the previous ReadWriteCloser. Any error returned by the io.ReadWriteCloser after the reset is replaced with ErrRWCReset. If it is reset before the write takes place, 0 is returned along with ErrRWCReset.