fwdobject

Documentation

Overview

Package fwdobject contains routines and interfaces used to implement various forwarding objects.

Lucius implements a variety of forwarding behaviors with the help of forwarding objects explictly created by provisioning. These objects are implemented as types satisfying the interface Object.

When a forwarding object is created in a context, the client specifies an object ID. The ID is a human readable opaque string used by provisioning for managing and updating this object or other objects. Additionally Lucius also assigns a NID for each object and uses it for its internal operations.

When provisioning removes an object, its ID is freed and the object is removed from the Table. After this point, provisioning cannot find the object using the ID. When the reference count of the object drops to zero, its NID is released to the pool and its entry is removed. In other words, the object cannot be found by ID after it is removed, and cannot be found by NID after all references drop to zero.

Provisioning can make and break links between objects. To track the correctness of these links, each object maintains a reference count. The reference count is incremented and decremented by the Aquire and Release methods respectively.

Note that when an object is created, the object's reference count is set to one. When the reference count drops to zero, the object is deleted. In a correctly behaving system, the reference count drops to zero only when provisioning explicitly removes an object.

An object may contain references to other objects. An object may also contain instances of types that are not directly managed by provisioning i.e. they are implicitly created when the object is created. These implicit types may in turn be composed of references to other objects. To ensure correct cleanup, all types (objects or non-objects) must implement the interface Composite.

Index

• Constants
• func MakeID(id ID) *fwdpb.ObjectId
• type Base
  • func (b *Base) Acquire() error
  • func (b *Base) Attributes() fwdattribute.Set
  • func (b *Base) BaseInfo() (str string)
  • func (b *Base) Counters() map[fwdpb.CounterId]Counter
  • func (b *Base) ID() ID
  • func (b *Base) Increment(id fwdpb.CounterId, delta uint32)
  • func (b *Base) Init(id ID, nid NID, cleanup func())
  • func (b *Base) InitCounters(desc string, ids ...fwdpb.CounterId) error
  • func (b *Base) NID() NID
  • func (b *Base) Release(forceCleanup bool) error
• type Composite
• type Counter
  • func (c *Counter) String() string
• type Counters
• type ID
  • func NewID(s string) ID
• type NID
• type NIDPool
  • func NewNIDPool(count uint64) *NIDPool
  • func (p *NIDPool) Acquire() (NID, error)
  • func (p *NIDPool) Release(id NID)
• type Object
• type Table
  • func NewTable() *Table
  • func (table *Table) Acquire(oid *fwdpb.ObjectId) (Object, error)
  • func (table *Table) FindID(oid *fwdpb.ObjectId) (Object, error)
  • func (table *Table) FindNID(nid NID) (Object, error)
  • func (table *Table) IDs() []ID
  • func (table *Table) Insert(object Object, oid *fwdpb.ObjectId) error
  • func (table *Table) Remove(oid *fwdpb.ObjectId, forceCleanup bool) error
  • func (table *Table) String() string

Constants

const InvalidID = ID("")

InvalidID represents a non existing ID.

const InvalidNID = NID(0)

InvalidNID represents an invalid NID.

Functions

func MakeID

func MakeID(id ID) *fwdpb.ObjectId

MakeID makes an ObjectID to the specified ID.

Types

type Base

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

A Base is a partial implementation of Object used to facilitate the implementation of a forwarding object. A forwarding object can be implemented as follows: 1. Embed a Base. 2. Implement String using a call to BaseInfo. 3. Implement Composite if it contains references to other Composites. A Base is not safe for simultaneous use by multiple goroutines.

func (*Base) Acquire

func (b *Base) Acquire() error

Acquire acquires a reference on the object.

func (*Base) Attributes

func (b *Base) Attributes() fwdattribute.Set

Attributes returns the set of attributes associated with the object.

func (*Base) BaseInfo

func (b *Base) BaseInfo() (str string)

BaseInfo formats the state of the object as a string.

func (*Base) Counters

func (b *Base) Counters() map[fwdpb.CounterId]Counter

Counters returns all available counters.

func (*Base) ID

func (b *Base) ID() ID

ID returns b's id.

func (*Base) Increment

func (b *Base) Increment(id fwdpb.CounterId, delta uint32)

Increment increments the specified counter if it exists.

func (*Base) Init

func (b *Base) Init(id ID, nid NID, cleanup func())

Init initalizes b's id and reference count.

func (*Base) InitCounters

func (b *Base) InitCounters(desc string, ids ...fwdpb.CounterId) error

InitCounters initializes all the counters that are maintained on the object. Note that this must be called before any call to Increment.

func (*Base) NID

func (b *Base) NID() NID

NID returns b's nid.

func (*Base) Release

func (b *Base) Release(forceCleanup bool) error

Release releases a reference on the object. If forceCleanup is set, object will be cleaned up regardless of refcount.

type Composite

type Composite interface {
	// Cleanup releases all references held by the struct.
	Cleanup()
}

Composite is an interface that must be implemented by objects that reference other objects.

type Counter

type Counter struct {
	ID    fwdpb.CounterId
	Value uint64
}

Counter is a counter id and its corresponding counter value.

func (*Counter) String

func (c *Counter) String() string

String formats the counter.

type Counters

type Counters interface {
	// Counters retrieves all available counters.
	Counters() map[fwdpb.CounterId]Counter

	// Increment increments the specified counter.
	Increment(id fwdpb.CounterId, delta uint32)
}

Counters is an interface to maintain counters that can be queried by provisioning and incremented while processing packets.

type ID

type ID string

ID is an opaque string used in the public API to identify a forwarding object within a context. The ID is an opaque string and is expected to be human readable.

func NewID

func NewID(s string) ID

NewID creates an ID from the specified string.

type NID

type NID uint64

NID is a numeric identifier of a forwarding object within a Lucius context.

type NIDPool

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

NIDPool is a pool used to generate object NIDs. It is not safe for simultaneous use by multiple goroutines.

func NewNIDPool

func NewNIDPool(count uint64) *NIDPool

NewNIDPool creates a pool with the specified number of object NIDs.

func (*NIDPool) Acquire

func (p *NIDPool) Acquire() (NID, error)

Acquire obtains a new object id.

func (*NIDPool) Release

func (p *NIDPool) Release(id NID)

Release releases an object id into the pool.

type Object

type Object interface {
	Counters

	// ID returns the object's ID.
	ID() ID

	// NID returns the object's NID.
	NID() NID

	// String formats the state of the object as a string.
	String() string

	// Acquire acquires a reference on the object.
	Acquire() error

	// Release releases a reference on the object.
	// If forceCleanup is set, the object is cleaned up regardless of references.
	Release(forceCleanup bool) error

	// Init initalizes the object's ID, NID, reference count and relevant
	// interfaces. It also sets a cleanup function called when the
	// object's reference count drops to zero
	Init(id ID, nid NID, cleanup func())

	// Attributes returns the set of attributes associated with the object.
	Attributes() fwdattribute.Set
}

Object is an interface for visible objects. A visible entity is an object that can be referenced by other objects or provisioning.

type Table

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

A Table is set of visible forwarding objects. Each object is indexed by its ID and NID.

func NewTable

func NewTable() *Table

NewTable returns a new empty object table.

func (*Table) Acquire

func (table *Table) Acquire(oid *fwdpb.ObjectId) (Object, error)

Acquire finds the object with the specific id and acquires a reference.

func (*Table) FindID

func (table *Table) FindID(oid *fwdpb.ObjectId) (Object, error)

FindID finds the object with the specific ID without acquiring a reference.

func (*Table) FindNID

func (table *Table) FindNID(nid NID) (Object, error)

FindNID finds the object with the specific NID without acquiring a reference.

func (*Table) IDs

func (table *Table) IDs() []ID

IDs returns a slice of object-ids.

func (*Table) Insert

func (table *Table) Insert(object Object, oid *fwdpb.ObjectId) error

Insert adds an object to the table and associates it with the specified object id. The object is also setup with a cleanup function that releases the NID and references held by the object, when the object's refcount drops to zero.

func (*Table) Remove

func (table *Table) Remove(oid *fwdpb.ObjectId, forceCleanup bool) error

Remove finds the object with the specific id and removes it from the table. It also releases the reference taken during the initial insert. Note that the object is findable by the NID until its refcount drops to zero. If forceCleanup is set, objects will be cleaned up regardless of refcount. forceCleanup should only be set during context deletion!

func (*Table) String

func (table *Table) String() string

String returns all the objects in a ';' delimited string format.