golang

README

golang

import "github.com/blueprint-uservices/blueprint/runtime/plugins/golang"

Package golang implements the golang namespace used by Blueprint applications at runtime to instantiate golang nodes.

A golang namespace takes care of the following:

• receives string arguments from the calling environment
• instantiates nodes that live in this namespace

Index

• func EnvVar(name string) string
• type BuildFunc
• type Namespace
  • func (n *Namespace) Await()
  • func (n *Namespace) Context() (ctx context.Context)
  • func (n *Namespace) Get(name string, receiver any) error
  • func (n *Namespace) Shutdown(awaitCompletion bool)
• type NamespaceBuilder
  • func NewNamespaceBuilder(name string) *NamespaceBuilder
  • func (b *NamespaceBuilder) Build(ctx context.Context) (*Namespace, error)
  • func (b *NamespaceBuilder) BuildWithParent(parent *Namespace) (*Namespace, error)
  • func (b *NamespaceBuilder) Define(name string, build BuildFunc)
  • func (b *NamespaceBuilder) Instantiate(name string)
  • func (b *NamespaceBuilder) Optional(name string, description string)
  • func (b *NamespaceBuilder) Required(name string, description string)
  • func (b *NamespaceBuilder) Set(name string, value string)
• type Runnable

func EnvVar

func EnvVar(name string) string

A utility function to deterministically convert a string into a a valid linux environment variable name. This is done by converting all punctuation characters to underscores, and converting alphabetic characters to uppercase (for convention), e.g.

a.grpc_addr becomes A_GRPC_ADDR.

Punctuation is converted to underscores, and alpha are made uppercase.

type BuildFunc

Constructs a node. Within a namespace, a BuildFunc will only be called once, when somebody calls Namespace.Get for the named node.

Namespaces reuse built nodes; subsequent calls to Namespace.Get will return the same built instance as the first invocation.

node is a runtime instance such as a service, a wrapper class, etc.

If node implements the Runnable interface then in addition to building the node. a namespace will also invoke [Runnable.Run] in a separate goroutine.

type BuildFunc func(n *Namespace) (node any, err error)

type Namespace

A namespace from which nodes can be fetched by name.

Nodes in the namespace can either be:

• argument nodes passed in to the namespace
• nodes built within this namespace.

A namespace is constructed using the NamespaceBuilder struct, which can be created with the NewNamespaceBuilder method.

The standard usage of a namespace is by a golang process. Any golang services, wrappers, etc. are created using a Namespace.

Some plugins, such as the ClientPool plugin, also use child Namespaces within the golang process Namespace.

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

func (*Namespace) Await

func (n *Namespace) Await()

If any nodes in this namespace are running goroutines, waits for them to finish

func (*Namespace) Context

func (n *Namespace) Context() (ctx context.Context)

ctx can be used by any BuildFunc that wants to start background goroutines, perform a blocking select, etc.

ctx will be notified on the Done channel if the namespace is shutdown during blocking.

func (*Namespace) Get

func (n *Namespace) Get(name string, receiver any) error

Gets a node from this namespace. If the node hasn't been built yet, it will be built.

func (*Namespace) Shutdown

func (n *Namespace) Shutdown(awaitCompletion bool)

Stops any nodes (e.g. servers) that are running in this namespace.

type NamespaceBuilder

The NamespaceBuilder is used at runtime by golang nodes to accumulate node definitions and configuration values for a namespace.

Use the NewNamespaceBuilder function to create a namespace builder.

Ultimately one of the Build methods should be called to create and start the namespace.

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

func NewNamespaceBuilder

func NewNamespaceBuilder(name string) *NamespaceBuilder

Instantiates a new NamespaceBuilder.

The NamespaceBuilder accumulates node and config variable definitions. Once all definitions are added, the Build* methods are used to build the namespace.

func (*NamespaceBuilder) Build

func (b *NamespaceBuilder) Build(ctx context.Context) (*Namespace, error)

Builds and returns the namespace. This will:

• check that all required nodes have been defined
• parse command line arguments looking for missing required nodes
• build any nodes that were specified with [Instantiate]

Returns a Namespace where nodes can now be gotten.

func (*NamespaceBuilder) BuildWithParent

func (b *NamespaceBuilder) BuildWithParent(parent *Namespace) (*Namespace, error)

Builds and returns the namespace. This will:

• check that all required nodes have been defined either in this namespace or in the parent namespace(s)
• NOT parse command line arguments
• build any nodes that were specified with [Instantiate], fetching missing nodes from the parent namespace

func (*NamespaceBuilder) Define

func (b *NamespaceBuilder) Define(name string, build BuildFunc)

Defines a build function for a node that can be built within this namespace.

name gives a name to the node that will be built.

build is a BuildFunc for building the node. build is lazily invoked when Get(name) is called on the Namespace

func (*NamespaceBuilder) Instantiate

func (b *NamespaceBuilder) Instantiate(name string)

Indicates that name should be eagerly built when the namespace is built.

The typical usage of this is to ensure that servers get started for namespaces that run servers.

func (*NamespaceBuilder) Optional

func (b *NamespaceBuilder) Optional(name string, description string)

Indicates that name is an optional node. An error will only be returned if the caller attempts to build the node.

The typical usage of this is when using only a single client from a client library

func (*NamespaceBuilder) Required

func (b *NamespaceBuilder) Required(name string, description string)

Indicates that name is a required node. When the namespace is built, an error will be returned if any required nodes are missing.

The typical usage of this is to eagerly validate that all command line arguments have been provided.

func (*NamespaceBuilder) Set

func (b *NamespaceBuilder) Set(name string, value string)

Sets a node to the specified value.

Typically this is used for setting configuration or argument variables.

type Runnable

If the return value of a BuildFunc implements the Runnable interface then the Namespace will automatically call [Runnable.Run] in a separate goroutine

type Runnable interface {
    // [Namespace] will call Run in a separate goroutine.
    Run(ctx context.Context) error
}

Generated by gomarkdoc

Documentation

Overview

Package golang implements the golang namespace used by Blueprint applications at runtime to instantiate golang nodes.

A golang namespace takes care of the following:

• receives string arguments from the calling environment
• instantiates nodes that live in this namespace

Index

• func EnvVar(name string) string
• type BuildFunc
• type Namespace
  • func (n *Namespace) Await()
  • func (n *Namespace) Context() (ctx context.Context)
  • func (n *Namespace) Get(name string, receiver any) error
  • func (n *Namespace) Shutdown(awaitCompletion bool)
• type NamespaceBuilder
  • func NewNamespaceBuilder(name string) *NamespaceBuilder
  • func (b *NamespaceBuilder) Build(ctx context.Context) (*Namespace, error)
  • func (b *NamespaceBuilder) BuildWithParent(parent *Namespace) (*Namespace, error)
  • func (b *NamespaceBuilder) Define(name string, build BuildFunc)
  • func (b *NamespaceBuilder) Instantiate(name string)
  • func (b *NamespaceBuilder) Optional(name string, description string)
  • func (b *NamespaceBuilder) Required(name string, description string)
  • func (b *NamespaceBuilder) Set(name string, value string)
• type Runnable

Functions

func EnvVar

func EnvVar(name string) string

A utility function to deterministically convert a string into a a valid linux environment variable name. This is done by converting all punctuation characters to underscores, and converting alphabetic characters to uppercase (for convention), e.g.

a.grpc_addr becomes A_GRPC_ADDR.

Punctuation is converted to underscores, and alpha are made uppercase.

Types

type BuildFunc

type BuildFunc func(n *Namespace) (node any, err error)

Constructs a node. Within a namespace, a BuildFunc will only be called once, when somebody calls Namespace.Get for the named node.

Namespaces reuse built nodes; subsequent calls to Namespace.Get will return the same built instance as the first invocation.

node is a runtime instance such as a service, a wrapper class, etc.

If node implements the Runnable interface then in addition to building the node. a namespace will also invoke [Runnable.Run] in a separate goroutine.

type Namespace

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

A namespace from which nodes can be fetched by name.

Nodes in the namespace can either be:

• argument nodes passed in to the namespace
• nodes built within this namespace.

A namespace is constructed using the NamespaceBuilder struct, which can be created with the NewNamespaceBuilder method.

The standard usage of a namespace is by a golang process. Any golang services, wrappers, etc. are created using a Namespace.

Some plugins, such as the ClientPool plugin, also use child Namespaces within the golang process Namespace.

func (*Namespace) Await

func (n *Namespace) Await()

If any nodes in this namespace are running goroutines, waits for them to finish

func (*Namespace) Context

func (n *Namespace) Context() (ctx context.Context)

ctx can be used by any BuildFunc that wants to start background goroutines, perform a blocking select, etc.

ctx will be notified on the Done channel if the namespace is shutdown during blocking.

func (*Namespace) Get

func (n *Namespace) Get(name string, receiver any) error

Gets a node from this namespace. If the node hasn't been built yet, it will be built.

func (*Namespace) Shutdown

func (n *Namespace) Shutdown(awaitCompletion bool)

Stops any nodes (e.g. servers) that are running in this namespace.

type NamespaceBuilder

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

The NamespaceBuilder is used at runtime by golang nodes to accumulate node definitions and configuration values for a namespace.

Use the NewNamespaceBuilder function to create a namespace builder.

Ultimately one of the Build methods should be called to create and start the namespace.

func NewNamespaceBuilder

func NewNamespaceBuilder(name string) *NamespaceBuilder

Instantiates a new NamespaceBuilder.

The NamespaceBuilder accumulates node and config variable definitions. Once all definitions are added, the Build* methods are used to build the namespace.

func (*NamespaceBuilder) Build

func (b *NamespaceBuilder) Build(ctx context.Context) (*Namespace, error)

Builds and returns the namespace. This will:

• check that all required nodes have been defined
• parse command line arguments looking for missing required nodes
• build any nodes that were specified with [Instantiate]

Returns a Namespace where nodes can now be gotten.

func (*NamespaceBuilder) BuildWithParent

func (b *NamespaceBuilder) BuildWithParent(parent *Namespace) (*Namespace, error)

Builds and returns the namespace. This will:

• check that all required nodes have been defined either in this namespace or in the parent namespace(s)
• NOT parse command line arguments
• build any nodes that were specified with [Instantiate], fetching missing nodes from the parent namespace

func (*NamespaceBuilder) Define

func (b *NamespaceBuilder) Define(name string, build BuildFunc)

Defines a build function for a node that can be built within this namespace.

name gives a name to the node that will be built.

build is a BuildFunc for building the node. build is lazily invoked when Get(name) is called on the Namespace

func (*NamespaceBuilder) Instantiate

func (b *NamespaceBuilder) Instantiate(name string)

Indicates that name should be eagerly built when the namespace is built.

The typical usage of this is to ensure that servers get started for namespaces that run servers.

func (*NamespaceBuilder) Optional

func (b *NamespaceBuilder) Optional(name string, description string)

Indicates that name is an optional node. An error will only be returned if the caller attempts to build the node.

The typical usage of this is when using only a single client from a client library

func (*NamespaceBuilder) Required

func (b *NamespaceBuilder) Required(name string, description string)

Indicates that name is a required node. When the namespace is built, an error will be returned if any required nodes are missing.

The typical usage of this is to eagerly validate that all command line arguments have been provided.

func (*NamespaceBuilder) Set

func (b *NamespaceBuilder) Set(name string, value string)

Sets a node to the specified value.

Typically this is used for setting configuration or argument variables.

type Runnable

type Runnable interface {
	// [Namespace] will call Run in a separate goroutine.
	Run(ctx context.Context) error
}

If the return value of a BuildFunc implements the Runnable interface then the Namespace will automatically call [Runnable.Run] in a separate goroutine