idxmap

README

Concept

The idxmap package provides an enhanced mapping structure to help in the following use cases:

• Caching the the data in key-value store (such as etcd)
• Exposing local plugin information - idxmap used for exposing one plugin's data to another plugins

For more detailed description see the godoc.

Caching Use Case

Imagine that you need the data from the key-value store cached (see following diagram) because you need to:

• either minimize lookups of the key-value store
• or you need to lookup by secondary indexes (fields of structured values stored in key value store)

Therefore idxmap can watch key value store, see:

• implementation of cache helper.go
• example of caching IP addresses of different containers

Exposing plugin local information Use Case

App plugin needs to expose some structured information to one or multiple app plugins inside the agent (see following diagram).

If this structured data is stored in idxmap then, multiple plugins can read its information

1. either via Lookup using primary keys or secondary indices;
2. or watching data changes in the map (using channels or callbacks) (subscribe for changes and receive notification once an item is added or removed).

Examples:

• Real world example from VPP-agent plugin API
• Isolated and simplified examples can be found here:
  • lookup
  • watch

Documentation

Overview

Package idxmap defines a mapping structure which supports mapping change notifications and retrieval of items by fields in the value structure.

Primary Index                Item                                Secondary indexes

===================================================================================

Eth1              +---------------------+                 { "IP" : ["192.168.2.1", "10.0.0.8"],
                  |  Status: Enabled    |                   "Type" : ["ethernet"]
                  |  IP: 192.168.2.1    |                 }
                  |      10.0.0.8       |
                  |  Type: ethernet     |
                  |  Desc: something    |
                  +---------------------+

Function `Put` adds a value (item) into the mapping. In the function call the primary index(name) for the item is specified. The values of the primary index are unique, if the name already exists, then the item is overwritten. To retrieve an item identified by the primary index, use the `GetValue` function. An item can be removed from the mapping by calling the `Delete` function. The names that are currently registered can be retrieved by calling the `ListAllNames` function.

The constructor allows you to define a `createIndexes` function that extracts secondary indices from stored items. The function returns a map indexed by names of secondary indexes, and the values are the extracted values for the particular item. The values of secondary indexes are not necessarily unique. To retrieve items based on secondary indices use the `ListNames` function. In contrast to the lookup by primary index, the function may return multiple names.

`Watch` allows to define a callback that is called when a change in the mapping occurs. There is a helper function `ToChan` available, which allows to deliver notifications through a channel.

Index

• Constants
• func ToChan(ch chan NamedMappingGenericEvent, opts ...interface{}) func(dto NamedMappingGenericEvent)
• type NamedMapping
• type NamedMappingEvent
• type NamedMappingGenericEvent
• type NamedMappingRW

Constants

const DefaultNotifTimeout = 2 * time.Second

DefaultNotifTimeout for delivery of notification

Functions

func ToChan

func ToChan(ch chan NamedMappingGenericEvent, opts ...interface{}) func(dto NamedMappingGenericEvent)

ToChan creates a callback that can be passed to the Watch function in order to receive notifications through a channel. If the notification can not be delivered until timeout it is dropped.

Types

type NamedMapping

type NamedMapping interface {
	// GetRegistryTitle returns the title assigned to the registry.
	GetRegistryTitle() string

	// GetValue retrieves a previously stored item identified by
	// name. If the 'exists' flag is set to false
	// upon return, there is no item associate with the give name in the mapping.
	GetValue(name string) (value interface{}, exists bool)

	// ListNames looks up the items by secondary indexes. It returns all
	// names matching the selection.
	ListNames(field string, value string) (names []string)

	// ListAllNames returns all names in the mapping.
	ListAllNames() (names []string)

	// Watch subscribes to receive notifications about the changes in the
	// mapping. To receive changes through channel ToChan utility can be used.
	//
	// Example usage:
	//
	//  map.Watch(plugin.PluginName, ToChan(myChannel))
	//
	//  map.Watch(plugin.PluginName, func(msgNamedMappingGenericEvent) {/*handle callback*/ return nil})
	//
	Watch(subscriber core.PluginName, callback func(NamedMappingGenericEvent)) error
}

NamedMapping is the "user API" to the mapping. It provides read-only access.

type NamedMappingEvent

type NamedMappingEvent struct {
	// The owner plugin of the registry (use also as namespace)
	Owner core.PluginName
	// Logical name of the object
	Name string
	// Del denotes a type of change
	// - it is true if an item was removed
	// - it false if an item was added or updated
	Del bool
	// RegistryTitle identifies the registry (NameToIndexMapping)
	RegistryTitle string
}

NamedMappingEvent is a part of change notification. It is a generic part that does not contain metadata of type interface{} thus it can be reused in mapping with typed metadata.

type NamedMappingGenericEvent

type NamedMappingGenericEvent struct {
	NamedMappingEvent

	Value interface{}
}

NamedMappingGenericEvent represents a single change in the mapping. The structure is created when an item is inserted or removed from the mapping.

type NamedMappingRW

type NamedMappingRW interface {
	NamedMapping

	// Put registers a new item into the mapping associated with the name.
	// Name is the primary unique key, if an item was registered before it is overwritten.
	Put(name string, value interface{})

	// Delete removes an item associated with the name from the mapping.
	Delete(name string) (value interface{}, exists bool)
}

NamedMappingRW is the "owner API" to the mapping. Using this API the owner can modify the content of the mapping.