Go Interfaces
External
Internal
Overview
An interface is a set of method signatures. Each signature contains the method name, optional parameter names and mandatory parameter types, and optional return variable names and mandatory return types. There is no method implementation.
Interfaces are not fully-featured types, they're less than that, but they're used to express conceptual similarities between types: if several types implement the same interface, they are similar in a way that is important to the application. An interface highlights the similarities between the types implementing it and conceals the differences.
Interface is declared with the keyword type, followed by the name of the interface, followed by the keyword interface.
A type implements (or satisfies) an interface if the type defines all methods specified in the interface. Of course, the type can have other methods not specified by the interface.
Interfaces can be thought of a kind of conceptual inheritance (types inherit behavior specified by an interface) and help with implementing polymorphism in Go.
Interfaces are not declared to be satisfied, they are satisfied implicitly.
"The bigger the interface, the weaker the abstraction." The most important thing about interfaces in Go is that the smaller the interface is, the more useful it is. This is a Go-specific idea: we want to make little interfaces, so we can build components that share them.
Go type system is structural, not nominal. The interfaces are behavior contracts, and they belong in the consuming code, not in the producing code. A common pattern should be to accept interfaces and return structs.
Define interface at the "fault lines" of your architecture. These are between the main() function and the rest, and along the package API boundaries.
Declaration
The following syntax declares an interface:
type <Interface_Name> interface {
<method_signature_1>
<method_signature_2>
...
}
Example:
type SomeInterface interface {
MethodA(int) (int, error) // No parameter and return value names are specified.
MethodB(someValue int) (someResult int, err error) // Parameter and return value names are provided.
// This is arguably clearer, as it conveys more semantics.
}
What results after such a declaration is an interface type. For a discussion of concrete type vs. interface types, see:
Idiomatic Interface Conventions
Single-method interfaces are named using the method name plus an "er" suffix. An interface with just one Write method would be called Writer.
Interfaces should not be defined before a realistic example of usage exists.
Return concrete types instead of interfaces in your functions, using a pointer or a struct.
Also see:
Implementing an Interface
As mentioned above, Interfaces are not declared to be satisfied, they are satisfied implicitly. The type satisfying an interface do not need to formally declare the name of the interface anywhere in its definition. Instead, it is sufficient to declare themselves as receiver types for all the methods in the interface declaration.
type Triangle { ... } // TwoDimensionalShape is specified nowhere in the Triangle declaration
// Declaring the type as receiver for *all* methods declared in the interface makes the type to implement that interface
func (t Triangle) Area() float64 { ... }
func (t Triangle) Perimeter() float64 { ... }
func (t Triangle) Merge(s TwoDimensionalShape) TwoDimensionalShape { ... }
Interface Values
Declaring a variable of an interface type creates an interface value.
The interface value is a pair that contains a dynamic type and a dynamic value. The dynamic type is a concrete type that implements that interface. The dynamic value is an instance of the dynamic type:
var i SomeInterface [...] // i is a pair: (dynamic_type, dynamic_value)
Assuming the following interface and concrete type declarations:
type SomeInterface interface {
SomeMethod()
}
type SomeType struct {
data string
}
// make the type implement the interface
func (v *SomeType) SomeMethod() {
if v != nil {
fmt.Printf("data: %s\n", v.data)
} else {
fmt.Println("invocation with a nil dynamic value")
}
}
the following variable declarations and initializations create an interface variable, a concrete type variable. The code then assigns the interface variable with the concrete type variable, which will make the interface value get the pair of a dynamic type (SomeType) and the dynamic value (v):
var i SomeInterface
var v = SomeType{"blue"}
i = v
The interface value can be then used to invoke the method on the dynamic concrete type instance (the dynamic value).
i.SomeMethod()
An interface value can have a nil dynamic value, and still be usable, as long it is assigned a dynamic type with this syntax:
var i SomeInterface
var v *SomeType // Declares "v" a pointer to the concrete type, not the concrete type (for some reason!)
i = v
Why do I need to declare *SomeType and not SomeType? It seems unnatural to assign a SomeInterface variable with a pointer to an implementing type.
An interface value assigned with a dynamic type (actually a pointer to the dynamic type) but not dynamic value can still be invoked into, given that the method implementation cases for the situation when the receiver type implicit argument is nil. In the example above, we assigned i a dynamic type, SomeType, but not a dynamic value, as v has no concrete value yet. The dynamic type is enough information to go find which implementation SomeMethod() should use. That is why it is a good idea to guard against nil implicit argument in all concrete methods provided by types that implement interfaces. This way you have a static (in the Java or Python sense of the world) method and an instance method at the same time.
i.SomeMethod() // prints "invocation with a nil dynamic value"
Having a dynamic type but no dynamic value is a legal state. It is a way to implement static (type) methods.
Does an interface always have a dynamic type?
nil Interface Value
This describes an interface value with a nil dynamic type. In this situation, you cannot call the methods on that interface, because without a dynamic type you can't know which method you are referring to.
Declaring an Interface-typed Function Parameter
Passing an Interface as a Function Argument
Empty Interface
An empty interface is an interface that specifies no methods. Any type can "implement" that interface. If you want to declare a parameter of any type for a function, make it an empty interface:
func SomeFunc(v interface{}) {
...
}
Rob Pike does not like empty interfaces: when you're programming and you use an empty interface, think really hard if this is actually what you want, or whether isn't just a little something you can put in, an interface with an actual method that is really necessary to capture the things you are talking about.
Using Interfaces
Function with Multiple Types of Parameters
Interface expresses similarity, so make the function take as a parameter an interface that expresses the similarity of all desired arguments.
func Area(s Shape) {
...
}
Type Assertions
An interface hides the differences between the types implementing it and emphasizes the commonality.
However, there are times you may want to know what exact concrete type exists behind the interface.
Type assertions can be used for type disambiguation:
var i SomeInterface
v, isType := i.(TypeName)
Usage example:
type SomeInterface interface {
SomeMethod()
}
type TypeA struct {
s string
}
func (v TypeA) SomeMethod() {
fmt.Println("TypeA.SomeMethod()")
}
type TypeB struct {
s string
}
func (v TypeB) SomeMethod() {
fmt.Println("TypeB.SomeMethod()")
}
func main() {
var i SomeInterface
i = TypeA{"A"}
b := TypeB{"B"}
a, isTypeA := i.(TypeA)
fmt.Printf("%v, %t\n", a, isTypeA) // will print {A}, true
b, isTypeB := i.(TypeB)
fmt.Printf("%v, %t\n", b, isTypeB) // will print {}, false
}
Type assertion with switch:
var i SomeInterface
i = TypeA{"A"}
switch v := i.(type) {
case TypeA:
fmt.Printf("TypeA: %v\n", v)
case TypeB:
fmt.Printf("TypeB: %v\n", v)
}
TO DEPLETE
Internal
Overview
Go has an unique interface system that allows programs to model behavior rather than model types: the behavior is "attached" to types via methods, and, independently, the behavior contract is defined by interfaces. The fact that a type implements an interface is not formally declared via a keyword, like in Java, or otherwise, but is an implicit consequence of a type "having" all the behavior declared by the interface. This is called duck typing. If a type implements an interface by the virtue of duck typing, a value of the type can be stored in a value of that interface type and the compiler ensure the assignments are correct at compile-time.
- Is this a good thing? As far as I can tell, I can't say whether a specific type implements an interface, short of browsing all methods in the package, looking for receivers of that specific type. The compiler does that easily, but I don't. This does not help code readability.
A type and its associated pointer type may or may not implement the same interface, depending on how the methods are "associated" with the value and pointers of that type. In order to understand how a type or its corresponding pointer type implements an interface, you need to understand method sets, which will be explained below. The notion of a type implementing an interface is related to method set inclusion. For more details see "When does a type/pointer type implement an interface?" below.
Any used-defined named type (structs, aliased types) can be made to implement interfaces.
The fact that Go detaches the contract from implementation with interfaces allows for polymorphism. Wen a method call is made against an interface value, the equivalent method of the stored user-defined type value it is executed. The user-defined type that implements an interface is often called a concrete type for that interface.
Interfaces in Go tend to be small, exposing only a few functions, or just one function.
Method Sets
A type may have a method set associated with it.
There are two kinds of method sets: interface method sets and user-defined types method sets. In the case of user-defined type method set, there's a distinction between the type method set and the pointer type method set, as it will be shown below.
If a type does not have any of the previously mentioned method sets, it is said to have an empty method set.
In a method set, each method must have a unique non-blank method name.
The language specification defines the method sets here: https://golang.org/ref/spec#Method_sets.
Interface Method Set
An interface method set is a list of method declarations (function name and signature), specified in the interface type declaration. The interface type declaration has the only purpose of defining the method set and giving it a name - the interface name.
The method set only contains method names and signatures, so the interface type does not define how the behavior is implemented, but just the behavior's contract. The interfaces allow us to hide the incidental details of the implementation. The behavior implementation details are contained by user-defined types, via methods.
Also, the method signatures from the interface method set are independent on whether the corresponding methods from the concrete types are declared with value or pointer receivers.
Interface Type
An interface type is a user-defined type whose only purpose is to introduce a method set (the interface method set) and to give it a name.
The interface type declaration starts with the type keyword, to indicated that this is a user-defined type, followed by the interface name and the keyword interface, followed by the interface method set declaration between curly braces. The interface method set declaration consists in a list of method names followed by their signatures. Unlike in the struct's case, we don't define fields.
type MyInterface interface {
<function-name-1><function-signature-1>
<function-name-2><function-signature-2>
...
}
Example:
type A interface {
m1(i int) int
m2(s string) string
}
Interface Name Convention
If the interface type contains only one method, the name of the interface starts with name of the method and ends with the er suffix. When multiple methods are declared within an interface type, the name of the interface should relate to its general behavior.
Interface
The method set of an interface type it is said to be the type's interface.
User-Defined Type Method Set
Method Set associated with the Values of a Type
The method set associated with the values of a type consists of all methods declared with a value receiver of that type.
The specification defines the method set of a type as the method set associated with the values of the type.
Method Set associated with the Pointers of a Type
The method set associated with the pointers of a type T consists of both all methods declared with a pointer receiver *T and with a value receiver T.
The method set associated with the pointers of a type always includes the method set associated with the values of the type. This is because given a pointer, we can always infer the value pointed by that address, so the methods associated with the value will naturally "work". The reverse is not true - given a value, not always we can get an address for it, and because we are not able to get an pointer, we cannot assume that the methods associated with the pointer will work. This is an example that demonstrates that we cannot always get an address for a value.
Another way of expressing this is that pointer receiver method are less general than the value receiver methods: value receiver methods can always be used, pointer receiver methods can't always be used.
Also see:
When does a Type/Pointer Type Implement an Interface?
Note that notion of a type implementing an interface and its corresponding pointer type implementing the same interface both make sense, and they are subtly different.
According to the language specification, a user-defined type T implements an interface if its method set (all methods declared with a value receiver of type T) is a superset of the interface.
By extrapolation, a pointer type implements an interface when the method set associated with pointers to that type is a superset of the interface. As per User-Defined Type Method Set section, the method set associated with the pointer of a type include implicitly the method set associated with the value of the type.
For more details about value and pointer receivers, see:
For more details about pointer types see:
Example
The example that follows shows how a type B implements interface A:
//
// The interface A declares an interface method set containing a single method m()
//
type A interface {
m()
}
//
// At this point, the type B is not yet linked to the interface A in any way.
// Its method set is empty, so it does not implement interface A, it does not
// implement any interface.
//
type B struct {
i int
}
//
// We make B implement interface A by declaring B as a value receiver for m().
// This means B's method set includes now m() and it is a superset of A's method
// set.
//
func (b B) m() {
// simply reports the value of i
fmt.Println(b.i)
}
...
//
// B now implements A, so B instances can be assigned to A variables
//
var a A
a = B{1}
a.m()
//
// *B now also implements A, because the method set of the pointer type
// includes the methods declared agains the value so *B instances
// can be assigned to A variables
//
var a2 A
a2 = &B{2}
a2.m()
...
A Variation of the Example
Note that if in the example above we declare
func (b *B) m() {
...
}
instead of
func (b B) m() {
...
}
then the a = B{1} assignment would fail to compile with:
./main.go:23: cannot use B literal (type B) as type A in assignment: B does not implement A (m method has pointer receiver)
This is because the type B does not implement the interface, because m() is not in the type B method set.
However, if we try:
var a A
a = &B{1}
a.m()
it works in both cases, because the method set associated with the B pointers include both func (b B) m() ... and func (b *B) m() ... so the pointer type B implements the interface.
Passing Interfaces to Functions
Interfaces can be used as arguments to functions. Passing an interface instance insures that the function body can rely on the fact the interface methods are available on the passed instance.
With the example above, we declare a function f() that expects an interface A and we pass a B instance when invoking the function:
...
type A interface {
m()
}
func (b B) m() {
...
}
func f(a A) {
a.m()
}
...
b := B{1}
f(b)
...
Note that the B instance can be passed by value (as in the example above) or by reference (as in the example below). Both cases work for reasons explained in the Method Set associated with the Pointers of a Type section:
...
b := B{1}
f(&b)
...
or (same thing)
... bPtr := new(B) f(bPtr) ...
Interfaces as Fields
Interfaces can be used as fields in structs.
Implementation Details
An interface variable is a two-word data structure.
The first word contains a pointer to an internal table called iTable, which contains type information about the stored value: the concrete type of the value that has been stored and a list of methods associated with the value. The second word is a reference to the stored value.
The combination of type information and pointer binds the relationship between the two values.