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:
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.
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.
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)
