norm

package module
v0.0.0-...-10b8dc8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 8, 2017 License: BSD-2-Clause Imports: 11 Imported by: 0

README

===

NACK-Oriented Reliable Multicast (NORM)

===

Install

  1. norm/protolib C++ libraries are included.
  2. go get -d github.com/aletheia7/norm
  3. cd $GOPATH/src/github.com/aletheia7/norm
  4. go generate

Examples

data_send_recv (normDataSend/normDataRecv)

Ready to run on one machine at 127.0.0.1:6003/6004

cd examples/data_send_recv 
go install
data_send_recv -h
data_send_recv -r &
data_send_recv -s

stream_send_recv (normStreamSend/normStreamRecv)

Ready to run on one machine at 127.0.0.1:6003/6004

cd examples/stream_send_recv 
go install
stream_send_recv -h
stream_send_recv -r &
stream_send_recv -s

file_send_recv (normFileSend/normFileRecv)

Ready to run on one machine at 127.0.0.1:6003/6004

cd examples/file_send_recv 
go install
file_send_recv -h
file_send_recv -r &
file_send_recv -s

NORM Support

License

Use of this source code is governed by a BSD-2-Clause license that can be found in the LICENSE file.

Documentation

Overview

Package norm provides reliable UDP using multicast and unicast sockets. norm is a cgo wrapper for NACK-Oriented Reliable Multicast (NORM). libnorm can replace TCP/IP, and in many use cases, provide greater performance.

The goal of this package is to provide a one-to-one functional feature set with libnorm. The main exception is the Instance object and NormGetNextEvent(). Instance will create one goroutine to talk to libnorm. Multiple Instance objects can be used when necessary. In addition, multiple Session objects can be used under one Instance.

The maximum Object_type_data size is limited to the largest []byte indexed by an int type. The maximum []byte on a 32 bit system is ~ 2 GB (math.MaxInt32). The maximum []byte on a 64 bit system is much greater (math.MaxInt64). One can send larger data than an int type by sending multiple Object_type_data messages, or using an Object_type_file, or Object_type_stream. This package could easily be extended to support larger Object_type_data types. Make a github.com issue if this is necessary.

The Object_type_file and Object_type_data data types are delivered reliably, however, objects can be delivered out-of-order. Object_type_stream is delivered reliably and bytes arrive in order, however, the application determines the message boundaries for a group of bytes.

The Object_type_data and Object_type_file data types will be retained (Object.Retain()/(NormObjectRetain()) automatically. The application must call Object.Release() to free memory when these Object_types are no longer used.

Package norm is safe for concurrent goroutine use.

Index

Constants

View Source
const (
	Max_rx_cache_limit = 16384
	Max_int            = int(^uint(0) >> 1)
)
View Source
const (
	// These events are bit flags and can be or'd together.
	// See Session.Set_events().
	Event_type_all                    = event_type_all
	Event_type_invalid                = event_type_invalid
	Event_type_tx_queue_vacancy       = event_type_tx_queue_vacancy
	Event_type_tx_queue_empty         = event_type_tx_queue_empty
	Event_type_tx_flush_completed     = event_type_tx_flush_completed
	Event_type_tx_watermark_completed = event_type_tx_watermark_completed
	Event_type_tx_cmd_sent            = event_type_tx_cmd_sent
	Event_type_tx_object_sent         = event_type_tx_object_sent
	Event_type_tx_object_purged       = event_type_tx_object_purged
	Event_type_tx_rate_changed        = event_type_tx_rate_changed
	Event_type_local_sender_closed    = event_type_local_sender_closed
	Event_type_remote_sender_new      = event_type_remote_sender_new
	Event_type_remote_sender_reset    = event_type_remote_sender_reset
	Event_type_remote_sender_address  = event_type_remote_sender_address
	Event_type_remote_sender_active   = event_type_remote_sender_active
	Event_type_remote_sender_inactive = event_type_remote_sender_inactive
	Event_type_remote_sender_purged   = event_type_remote_sender_purged
	Event_type_rx_cmd_new             = event_type_rx_cmd_new
	Event_type_rx_object_new          = event_type_rx_object_new
	Event_type_rx_object_info         = event_type_rx_object_info
	Event_type_rx_object_updated      = event_type_rx_object_updated

	// Not sent for Object_type_stream until Stream_close()
	// Object_type_data and Object_type_file are retained (Object.Retain())
	// automatically. Must call Object.Release() to release memory.
	Event_type_rx_object_completed = event_type_rx_object_completed

	Event_type_rx_object_aborted = event_type_rx_object_aborted
	Event_type_grtt_updated      = event_type_grtt_updated
	Event_type_cc_active         = event_type_cc_active
	Event_type_cc_inactive       = event_type_cc_inactive
	Event_type_acking_node_new   = event_type_acking_node_new
	Event_type_send_error        = event_type_send_error // ICMP error (e.g. destination unreachable)
	Event_type_user_timeout      = event_type_user_timeout
)

NormDeveloperGuide.html events:

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#d0e1384

View Source
const (
	Object_type_none   Object_type = object_type_none
	Object_type_data               = object_type_data
	Object_type_file               = object_type_file
	Object_type_stream             = object_type_stream
)
View Source
const (
	Ack_invalid Acking_status = ack_invalid
	Ack_failure               = ack_failure
	Ack_pending               = ack_pending
	Ack_success               = ack_success
)
View Source
const (
	Nack_none      Nacking_mode = nack_none
	Nack_info_only              = nack_info_only
	Nack_normal                 = nack_normal
)
View Source
const (
	Flush_none    Flush_mode = flush_none
	Flush_passive            = flush_passive
	Flush_active             = flush_active
)
View Source
const (
	Probe_none    Probe_mode = probe_none
	Probe_passive            = probe_passive
	Probe_active             = probe_active
)

Variables

View Source
var (
	E_session_invalid               = errors.New("session invalid")
	E_object_invalid                = errors.New("object invalid")
	E_false                         = errors.New("false")
	E_sender_sessions_not_destroyed error
)

Functions

This section is empty.

Types

type Acking_status

type Acking_status norm_acking_status

func (Acking_status) String

func (o Acking_status) String() string

type Event

type Event struct {
	Type    Event_type
	O       *Object
	Node    *Node
	Grtt    float64
	Tx_rate float64
}

func (Event) String

func (o Event) String() string

type Event_type

type Event_type uint

func (Event_type) String

func (o Event_type) String() string

type Flush_mode

type Flush_mode int

func (Flush_mode) String

func (o Flush_mode) String() string

type Instance

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

func Create_instance

func Create_instance(wg *sync.WaitGroup) (r *Instance, err error)

If wg is not nil, wg.Add()/wg.Done() will be called for the internal goroutine thus allowing for a clean shutdown.

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormCreateInstance

func (*Instance) Get_debug

func (o *Instance) Get_debug() bool

Get_debug applies to Instance and not libnorm.

func (*Instance) Get_debug_level

func (o *Instance) Get_debug_level() uint

func (*Instance) Get_version

func (o *Instance) Get_version() string

func (*Instance) Set_debug

func (o *Instance) Set_debug(debug bool)

Set_debug applies to Instance and not libnorm.

func (*Instance) Set_debug_level

func (o *Instance) Set_debug_level(debug_level uint)

debug_level: 3, set between 0 and 12 inclusive.

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormSetDebugLevel

type Nacking_mode

type Nacking_mode norm_nacking_mode

func (Nacking_mode) String

func (o Nacking_mode) String() string

type Node

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

func (*Node) Get_address

func (o *Node) Get_address() (address string, port uint16, success bool)

Returns: address ("127.0.0.1") and port, or nil

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormNodeGetAddress

func (*Node) Get_address_all

func (o *Node) Get_address_all() string

Returns: address:port ("127.0.0.1:32233") or nil

func (*Node) Get_command

func (o *Node) Get_command() (cmd *bytes.Buffer)

Returns: cmd will contain the command or be empty and non-nil.

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormNodeGetCommand

type Node_id

type Node_id norm_node_id
var (
	Node_none Node_id = node_none
	Node_any          = node_any
)

func (Node_id) String

func (o Node_id) String() string

type Object

type Object struct {
	// sequential integer (1 based) per Instance
	Id uint64
	// contains filtered or unexported fields
}

func (*Object) Data_detach_data

func (o *Object) Data_detach_data()

Use Data_access_data()

func (*Object) Is_retained

func (o *Object) Is_retained() bool

func (Object) String

func (o Object) String() string

Only Id and Type.

type Object_type

type Object_type uint32

func (Object_type) String

func (o Object_type) String() string

type Probe_mode

type Probe_mode int

func (Probe_mode) String

func (o Probe_mode) String() string

type Repair_boundary

type Repair_boundary norm_repair_boundary
const (
	Boundary_block  Repair_boundary = repair_block
	Boundary_object                 = repair_object
)

func (Repair_boundary) String

func (o Repair_boundary) String() string

type Session

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

func (*Session) Data_enqueue

func (o *Session) Data_enqueue(data, info []byte) (*Object, error)

Sender func

Data_enqueue does not copy data or info. Do not modify info and data until an Event_type_tx_object_purged is received for the returned *Object.Id. Object_type_data and Object_type_file objects are received in the Event_type_rx_object_completed Event.O.Data.

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormDataEnqueue

func (*Session) Events

func (o *Session) Events() <-chan *Event

func (*Session) File_enqueue

func (o *Session) File_enqueue(file_name string, info []byte) (*Object, error)

Sender func

Instance.Set_cache_directory() must be called in the Session Receiver in order for file transfers to occur.

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormFileEnqueue

func (*Session) Get_events

func (o *Session) Get_events() Event_type

func (*Session) Get_user_data

func (o *Session) Get_user_data() interface{}

Sender func

func (*Session) Requeue_object

func (o *Session) Requeue_object(obj *Object) bool

Sender func

Really only useful for silent non-nacking receivers.

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormRequeueObject

func (*Session) Set_congestion_control

func (o *Session) Set_congestion_control(enable, adjust_rate bool)

Sender func

enable: recommended is true. adjust_rate: recommended is true, false is experimental.

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormSetCongestionControl

func (*Session) Set_events

func (o *Session) Set_events(events Event_type)

Set_events determines the events that are delivered through the Session.Events() channel. events is a bit flag. Default: Event_type_all

var sess Session
log.Println(sess.Get_events()) // Output: Event_type_all

// Event_type_all minus Event_type_grtt_updated minus Event_type_tx_object_sent
sess.Set_events(sess.Get_events() &^ (Event_type_grtt_updated | Event_type_tx_object_sent))

func (*Session) Set_message_trace

func (o *Session) Set_message_trace(trace bool)

func (*Session) Set_rx_cache_limit

func (o *Session) Set_rx_cache_limit(rx_cache_limit int)

Receiver func

Call before Start_receiver()

default: 256, max: Max_rx_cache_limit

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormSetRxCacheLimit

func (*Session) Set_rx_port_reuse

func (o *Session) Set_rx_port_reuse(rx_port_reuse bool, rx_bind_address, rx_sender_address string, rx_sender_address_port uint16)

rx_address: can be nil

rx_send_address can be nil

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormSetRxPortReuse

func (*Session) Set_tx_cache_bounds

func (o *Session) Set_tx_cache_bounds(size_max uint, count_min, count_max uint32)

Sender func

defaults: size_max = 20 Mbyte, count_min = 8, recommended min = 2, count_max = 256

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormSetTxCacheBounds

func (*Session) Set_tx_port

func (o *Session) Set_tx_port(tx_port uint16, tx_port_reuse bool, tx_bind_address string) bool

default: session port in Instance.Create_session().

address can be nil. tx_port_reuse default: false.

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormSetTxPort

func (*Session) Set_user_data

func (o *Session) Set_user_data(user_data interface{})

Sender func

Set_user_data stores data with the Session. Set_user_data does not store user_data in Norm.

func (*Session) Start_sender

func (o *Session) Start_sender(id uint32, buffer_space uint, segment_size, block_size, num_parity uint16, fec_id uint8) bool

Sender func

defaults: id: 0 = set to time.Now(), buffer_space: 0 = 1024 * 1024, block_size: 0 = 64, num_parity: 0 = 16.

https://htmlpreview.github.io/?https://github.com/aletheia7/norm/blob/master/norm/doc/NormDeveloperGuide.html#NormStartSender

type Sync_policy

type Sync_policy norm_sync_policy
const (
	Sync_current Sync_policy = sync_current
	Sync_all                 = sync_all
)

func (Sync_policy) String

func (o Sync_policy) String() string

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL