What is the difference between Pointer and Value receiver types?

Question

I was writing a program that reads data from a io.Reader and caches them in a bytes.Buffer.

type SecureReader struct {
    pipe      io.Reader
    shared    *[32]byte
    decrypted bytes.Buffer
}

func (s SecureReader) Read(b []byte) (int, error) {
    s.decryptPipeIntoBuffer()
    return s.decrypted.Read(b)
}

func (s SecureReader) decryptPipeIntoBuffer() (int, error) {/*Lots of code...*/}

I first used a value receiver, because I thought they were the same. However, I noticed my method does not do anything when invoked: SecureReader.Read() would always return io.EOF.

I banged my head around and changed the receiver type to

func (s *SecureReader) decryptPipeIntoBuffer() (int, error) {/*Lots of code...*/}

Now my code magically works. What is going on?

Answer 1

A value receiver operates on a copy of the SecureReader instance s.

If the method mutates any part of the copy of the instance (like modify s.decrypted), it is not visible on the original instance of the receiver, once the method exit.

That changes with a pointer receiver, where the method operates and can mutates the actual SecureReader instance s, since a copy of the pointer is passed to the method.

---

See more examples in "Don't Get Bitten by Pointer vs Non-Pointer Method Receivers in Golang".

Simply stated: you can treat the receiver as if it was an argument being passed to the method. All the same reasons why you might want to pass by value or pass by reference apply.

Reasons why you would want to pass by reference as opposed to by value:

• You want to actually modify the receiver (“read/write” as opposed to just “read”)
• The struct is very large and a deep copy is expensive
• Consistency: if some of the methods on the struct have pointer receivers, the rest should too. This allows predictability of behavior

If you need these characteristics on your method call, use a pointer receiver.