Value receiver vs. pointer receiver

It is very unclear for me in which case I would want to use a value receiver instead of always using a pointer receiver.

To recap from the docs:

type T struct {
	a int
}
func (tv  T) Mv(a int) int         { return 0 }  // value receiver
func (tp *T) Mp(f float32) float32 { return 1 }  // pointer receiver

The docs also say "For types such as basic types, slices, and small structs, a value receiver is very cheap so unless the semantics of the method requires a pointer, a value receiver is efficient and clear."

First point they docs say a value receiver is "very cheap", but the question is whether it is cheaper than a pointer receiver. So I made a small benchmark (code on gist) which showed me, that pointer receiver is faster even for a struct that has only one string field. These are the results:

// Struct one empty string property
BenchmarkChangePointerReceiver  2000000000               0.36 ns/op
BenchmarkChangeItValueReceiver  500000000                3.62 ns/op


// Struct one zero int property
BenchmarkChangePointerReceiver  2000000000               0.36 ns/op
BenchmarkChangeItValueReceiver  2000000000               0.36 ns/op

(Edit: Please note that second point became invalid in newer go versions, see comments.)

Second point the docs say that a value receiver it is "efficient and clear" which is more a matter of taste, isn't it? Personally I prefer consistency by using the same thing everywhere. Efficiency in what sense? Performance wise it seems pointer are almost always more efficient. Few test-runs with one int property showed minimal advantage of Value receiver (range of 0.01-0.1 ns/op)

Can someone tell me a case where a value receiver clearly makes more sense than a pointer receiver? Or am I doing something wrong in the benchmark? Did I overlook other factors?

Note that the FAQ does mention consistency

> Next is consistency. If some of the methods of the type must have pointer receivers, the rest should too, so the method set is consistent regardless of how the type is used. See the section on method sets for details.

As mentioned in this thread:

> The rule about pointers vs. values for receivers is that value methods can
be invoked on pointers and values, but pointer methods can only be invoked
on pointers

Which is not true, as commented by Sart Simha

> Both value receiver and pointer receiver methods can be invoked on a correctly-typed pointer or non-pointer.
>
> Regardless of what the method is called on, within the method body the identifier of the receiver refers to a by-copy value when a value receiver is used, and a pointer when a pointer receiver is used: example.

Now:

> Can someone tell me a case where a value receiver clearly makes more sense then a pointer receiver?

The Code Review comment can help:

> - If the receiver is a map, func or chan, don't use a pointer to it.
>- If the receiver is a slice and the method doesn't reslice or reallocate the slice, don't use a pointer to it.
>- If the method needs to mutate the receiver, the receiver must be a pointer.
>- If the receiver is a struct that contains a sync.Mutex or similar synchronizing field, the receiver must be a pointer to avoid copying.
>- If the receiver is a large struct or array, a pointer receiver is more efficient. How large is large? Assume it's equivalent to passing all its elements as arguments to the method. If that feels too large, it's also too large for the receiver.
>- Can function or methods, either concurrently or when called from this method, be mutating the receiver? A value type creates a copy of the receiver when the method is invoked, so outside updates will not be applied to this receiver. If changes must be visible in the original receiver, the receiver must be a pointer.
>- If the receiver is a struct, array or slice and any of its elements is a pointer to something that might be mutating, prefer a pointer receiver, as it will make the intention more clear to the reader.
>- If the receiver is a small array or struct that is naturally a value type (for instance, something like the time.Time type), with no mutable fields and no pointers, or is just a simple basic type such as int or string, a value receiver makes sense.
A value receiver can reduce the amount of garbage that can be generated; if a value is passed to a value method, an on-stack copy can be used instead of allocating on the heap. (The compiler tries to be smart about avoiding this allocation, but it can't always succeed.) Don't choose a value receiver type for this reason without profiling first.
>- Finally, when in doubt, use a pointer receiver.

Note on "If the receiver is a slice and the method doesn't reslice or reallocate the slice, don't use a pointer to it."

The statement is suggesting that if you have a method that reslices or reallocates the slice, then you should use a pointer receiver.

In other words, if you modify the slice within the method, such as appending elements or changing the length/capacity of the slice, it's recommended to use a pointer receiver.

In the case of implementing deletion and insertion methods for a slice type, you will likely be modifying the slice (changing its length, appending or removing elements). Therefore, you should use a pointer receiver for these methods.

Example (playground):

package main

import "fmt"

type MySlice []int

func (s *MySlice) Insert(index int, value int) {
    // Insert value at index and shift elements
    *s = append((*s)[:index], append([]int{value}, (*s)[index:]...)...)
}

func (s *MySlice) Delete(index int) {
    // Remove the element at index and shift elements
    *s = append((*s)[:index], (*s)[index+1:]...)
}

func main() {
    s := MySlice{1, 2, 3, 4, 5}
    s.Insert(2, 42)
    fmt.Println(s) // Output: [1 2 42 3 4 5]

    s.Delete(2)
    fmt.Println(s) // Output: [1 2 3 4 5]
}

In this example, the Insert and Delete methods are modifying the slice by appending and removing elements.
As a result, a pointer receiver is used to ensure the modifications are visible outside the method.

The part in bold is found for instance in net/http/server.go#Write():

// Write writes the headers described in h to w.
//
// This method has a value receiver, despite the somewhat large size
// of h, because it prevents an allocation. The escape analysis isn't
// smart enough to realize this function doesn't mutate h.
func (h extraHeader) Write(w *bufio.Writer) {
...
}

Note: irbull points out in the comments a warning about interface methods:

> Following the advice that the receiver type should be consistent, if you have a pointer receiver, then your (p *type) String() string method should also use a pointer receiver.
>
> But this does not implement the Stringer interface, unless the caller of your API also uses pointer to your type, which might be a usability problem of your API.
>
> I don't know if consistency beats usability here.

points out to:

• "Method Sets (Pointer vs Value Receiver)"

> you can mix and match methods with value receivers and methods with pointer receivers, and use them with variables containing values and pointers, without worrying about which is which.
Both will work, and the syntax is the same.
>
> However, if methods with pointer receivers are needed to satisfy an interface, then only a pointer will be assignable to the interface — a value won't be valid.

• "Go interfaces and automatically generated functions" from Chris Siebenmann (June 2017)

> Calling value receiver methods through interfaces always creates extra copies of your values.
>
Interface values are fundamentally pointers, while your value receiver methods require values; ergo every call requires Go to create a new copy of the value, call your method with it, and then throw the value away.
There is no way to avoid this as long as you use value receiver methods and call them through interface values; it's a fundamental requirement of Go.

• "Learning about Go's unaddressable values and slicing" (still from Chris (Sept. 2018))

> Concept of unaddressable values, which are the opposite of addressable values. The careful technical version is in the Go specification in Address operators, but the hand waving summary version is that most anonymous values are not addressable (one big exception is composite literals)

To add additionally to @VonC great, informative answer.

I am surprised no one really mentioned the maintainance cost once the project gets larger, old devs leave and new one comes. Go surely is a young language.

Generally speaking, I try to avoid pointers when I can but they do have their place and beauty.

I use pointers when:

• working with large datasets
• have a struct maintaining state, e.g. TokenCache,
• • I make sure ALL fields are PRIVATE, interaction is possible only via defined method receivers
• • I don't pass this function to any goroutine

E.g:

type TokenCache struct {
    cache map[string]map[string]bool
}

func (c *TokenCache) Add(contract string, token string, authorized bool) {
    tokens := c.cache[contract]
    if tokens == nil {
        tokens = make(map[string]bool)
    }

    tokens[token] = authorized
    c.cache[contract] = tokens
}

Reasons why I avoid pointers:

• pointers are not concurrently safe (the whole point of GoLang)
• once pointer receiver, always pointer receiver (for all Struct's methods for consistency)
• mutexes are surely more expensive, slower and harder to maintain comparing to the "value copy cost"
• speaking of "value copy cost", is that really an issue? Premature optimization is root to all evil, you can always add pointers later
• it directly, conciously forces me to design small Structs
• pointers can be mostly avoided by designing pure functions with clear intention and obvious I/O
• garbage collection is harder with pointers I believe
• easier to argue about encapsulation, responsibilities
• keep it simple, stupid (yes, pointers can be tricky because you never know the next project's dev)
• unit testing is like walking through pink garden (slovak only expression?), means easy
• no NIL if conditions (NIL can be passed where a pointer was expected)

My rule of thumb, write as many encapsulated methods as possible such as:

package rsa

// EncryptPKCS1v15 encrypts the given message with RSA and the padding scheme from PKCS#1 v1.5.
func EncryptPKCS1v15(rand io.Reader, pub *PublicKey, msg []byte) ([]byte, error) {
    return []byte("secret text"), nil
}

cipherText, err := rsa.EncryptPKCS1v15(rand, pub, keyBlock) 

UPDATE:

This question inspired me to research the topic more and write a blog post about it https://medium.com/gophersland/gopher-vs-object-oriented-golang-4fa62b88c701

It is a question of semantics. Imagine you write a function taking two numbers as arguments. You don't want to suddenly find out that either of these numbers got mutated by the calling function. If you pass them as pointers that is possible. Lots of things should act just like numbers. Things like points, 2D vectors, dates, rectangles, circles etc. These things don't have identity. Two circle at the same position and with the same radius should not be distinguished from each other. They are value types.

But something like a database connection or a file handle, a button in the GUI is something where identity matters. In these cases you want a pointer to the object.

When something is inherently a value type such as a rectangle or point, it is really preferable to be able to pass them without using pointers. Why? Because it means you are certain to avoid mutating the object. It clarifies semantics and intent to reader of your code. It is clear that the function receiving the object cannot and will not mutate the object.