grpc – google.golang.org/grpc/attributes Index | Examples | Files

package attributes

import "google.golang.org/grpc/attributes"

Package attributes defines a generic key/value store used in various gRPC components.

Experimental

Notice: This package is EXPERIMENTAL and may be changed or removed in a later release.

Index

Examples

Types

type Attributes 

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

Attributes is an immutable struct for storing and retrieving generic key/value pairs. Keys must be hashable, and users should define their own types for keys. Values should not be modified after they are added to an Attributes or if they were received from one. If values implement 'Equal(o any) bool', it will be called by (*Attributes).Equal to determine whether two values with the same key should be considered equal.

Example

Code:play  

package main

import (
	"fmt"

	"google.golang.org/grpc/attributes"
)

type stringVal struct {
	s string
}

func (s stringVal) Equal(o any) bool {
	os, ok := o.(stringVal)
	return ok && s.s == os.s
}

func main() {
	type keyOne struct{}
	type keyTwo struct{}
	a := attributes.New(keyOne{}, 1).WithValue(keyTwo{}, stringVal{s: "two"})
	fmt.Println("Key one:", a.Value(keyOne{}))
	fmt.Println("Key two:", a.Value(keyTwo{}))
}

Output:

Key one: 1
Key two: {two}

func New 

func New(key, value any) *Attributes

New returns a new Attributes containing the key/value pair.

func (*Attributes) Equal 

func (a *Attributes) Equal(o *Attributes) bool

Equal returns whether a and o are equivalent. If 'Equal(o any) bool' is implemented for a value in the attributes, it is called to determine if the value matches the one stored in the other attributes. If Equal is not implemented, standard equality is used to determine if the two values are equal. Note that some types (e.g. maps) aren't comparable by default, so they must be wrapped in a struct, or in an alias type, with Equal defined.

func (*Attributes) MarshalJSON 

func (a *Attributes) MarshalJSON() ([]byte, error)

MarshalJSON helps implement the json.Marshaler interface, thereby rendering the Attributes correctly when printing (via pretty.JSON) structs containing Attributes as fields.

Is it impossible to unmarshal attributes from a JSON representation and this method is meant only for debugging purposes.

func (*Attributes) String 

func (a *Attributes) String() string

String prints the attribute map. If any key or values throughout the map implement fmt.Stringer, it calls that method and appends.

Example

Code:play  

package main

import (
	"fmt"

	"google.golang.org/grpc/attributes"
)

type stringVal struct {
	s string
}

func (s stringVal) Equal(o any) bool {
	os, ok := o.(stringVal)
	return ok && s.s == os.s
}

type stringerVal struct {
	s string
}

func (s stringerVal) String() string {
	return s.s
}

func main() {
	type key struct{}
	var typedNil *stringerVal
	a1 := attributes.New(key{}, typedNil)            // typed nil implements [fmt.Stringer]
	a2 := attributes.New(key{}, (*stringerVal)(nil)) // typed nil implements [fmt.Stringer]
	a3 := attributes.New(key{}, (*stringVal)(nil))   // typed nil not implements [fmt.Stringer]
	a4 := attributes.New(key{}, nil)                 // untyped nil
	a5 := attributes.New(key{}, 1)
	a6 := attributes.New(key{}, stringerVal{s: "two"})
	a7 := attributes.New(key{}, stringVal{s: "two"})
	a8 := attributes.New(1, true)
	fmt.Println("a1:", a1.String())
	fmt.Println("a2:", a2.String())
	fmt.Println("a3:", a3.String())
	fmt.Println("a4:", a4.String())
	fmt.Println("a5:", a5.String())
	fmt.Println("a6:", a6.String())
	fmt.Println("a7:", a7.String())
	fmt.Println("a8:", a8.String())
}

Output:

a1: {"<%!p(attributes_test.key={})>": "<nil>" }
a2: {"<%!p(attributes_test.key={})>": "<nil>" }
a3: {"<%!p(attributes_test.key={})>": "<0x0>" }
a4: {"<%!p(attributes_test.key={})>": "<%!p(<nil>)>" }
a5: {"<%!p(attributes_test.key={})>": "<%!p(int=1)>" }
a6: {"<%!p(attributes_test.key={})>": "two" }
a7: {"<%!p(attributes_test.key={})>": "<%!p(attributes_test.stringVal={two})>" }
a8: {"<%!p(int=1)>": "<%!p(bool=true)>" }

func (*Attributes) Value 

func (a *Attributes) Value(key any) any

Value returns the value associated with these attributes for key, or nil if no value is associated with key. The returned value should not be modified.

func (*Attributes) WithValue 

func (a *Attributes) WithValue(key, value any) *Attributes

WithValue returns a new Attributes containing the previous keys and values and the new key/value pair. If the same key appears multiple times, the last value overwrites all previous values for that key. To remove an existing key, use a nil value. value should not be modified later.

Example

Code:play  

package main

import (
	"fmt"

	"google.golang.org/grpc/attributes"
)

type stringVal struct {
	s string
}

func (s stringVal) Equal(o any) bool {
	os, ok := o.(stringVal)
	return ok && s.s == os.s
}

func main() {
	type keyOne struct{}
	type keyTwo struct{}
	a := attributes.New(keyOne{}, 1)
	a = a.WithValue(keyTwo{}, stringVal{s: "two"})
	fmt.Println("Key one:", a.Value(keyOne{}))
	fmt.Println("Key two:", a.Value(keyTwo{}))
}

Output:

Key one: 1
Key two: {two}

Source Files

attributes.go

Version
v1.70.0 (latest)
Published
Jan 23, 2025
Platform
linux/amd64
Imports
2 packages
Last checked
17 hours ago –

Tools for package owners.