mrnesbits

package module
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Jul 29, 2024 License: MIT Imports: 16 Imported by: 3

README

Multi-resolution network emulation-simulation for BITS

MrNesbits

The mrnesbits package (Multi-Resolution Network Emulation and Simulation for BITS) is used to model applications that execute on a mrnes network model. At the most basic level, an application is compromised of elements (called ‘functions’) that receive messages, execute some computation based on the message and its source, and optionally send messages in response to other functions. mrnesbits model syntax defines the topological structure of these applications (called “Computational Patterns”), describes how messages flow between functions, the function’s individual states, and references methods embedded in the simulator that are called to modify those states as messages are processed.

A foundational principle for mrnesbits models is that the simulation time associated with the execution of a function come from a look-up table that holds multiple measurements of that execution time on different CPUs, and under other model dependent parameters (e.g. number of bytes in a message being processed by the function). Another foundational principle is that mrnesbits allow for a large degree of flexibility and specialization in modeling the behavior of modeled software that calls these measured functions. It does so by organizing the flow of control of a simulation at a level of abstraction and through an API that allows for different ‘class’ dependent behavior of functions. Control of function behavior with associated virtual time delays explicitly supports representation of the impact of queuing and contention for processor and communication network resources, so that evaluation of mrnesbits models can capture the impact of congestion at different levels of the system.

mrnes and mrnesbits models are built using the discrete-event simulation paradigm, and use functionality given by the vrtime,evtq, and evtm packages. The models are explicitly event-oriented (as opposed to “process” oriented models that use discrete-event formulations under the covers, not explicitly viewable by the modeler). The simulation clock uses 64 bit integers for time ’ticks’, and 64 bit integers for tie- breaking events whose number of clock ticks are precisely the same. The vrtime package allows one to define the time duration of a tick to be whatever time-scale is of interest to the modeler; for our models of computer and communications activities we typically define a tick to represent 1/10 of a nanosecond.

mrnesbits directory

The mrnesbits simulator reads various files to prepare for and execute a simulation experiment. Those files are in .json or .yaml format that are read in and converted to Golang structs at simulator start-up. We describe below the role of methods and data structures found in various files in the MrNesbits package.

Files used as part of model-building

The files below have methods that are typically called to either build mrnesbits models, or read from file descriptions of models that have been built.

  • desc-cp.go This file holds definitions of those structs related to Computational Patterns and their initializations. It contains methods used by the simulator to read in those structs, and also contains methods that a separate external Golang program can use to build and store examples of those structs for specific classes of mrnesbits models.
  • desc-crypto.go The GUI should present selection options for crypto algorithms that are supported by measurements available to the simulator. This file holds struct definitions for a file that is read in by the GUI to guide those options, a file that is created by pre-model-building analysis using methods of data structures that holding function timing measurements.
  • desc-map.go Prior to model execution, its functions have to be mapped to processors in the declared architecture model. This file holds structs and methods that support creation and access to these mappings.
  • desc-params.go mrnesbits supports a rich syntax for describing parameter values (e.g. the bandwidth of interfaces) to a model description before a simulation run. This file contains structs and methods that are used for that purpose.
  • desc-timing.go This file holds definition of structs that specify identities of computation functions and their execution timing as a function of the underlaying hardware platform and ‘packet length’ associated with the data being operated on. The file contains methods for creating these structs from an external Golang program, and methods used by the simulator to read those structs in from file.
Files used as part of model-execution
  • class.go mrnesbit func belong to ‘classes’ with pre-defined structs and methods used in the simulated execution of those functions. This file contains the structs, other data structures, methods, and event handling routines for all of the pre-declared classes.
  • cpf.go The mrnesbits internals represent its functions through a type it calls a CmpPtnFuncInst (Computation Pattern Function Instance). This file defines this type and methods involved in initializing and simulating the execution of func instances.
  • cpg.go mrnesbits funcs are organized within so-called ‘Computation Patterns’, instances of which are represented by type CmpPtnInst, and which are fundamentally a graph whose nodes are CmpPtnFuncInsts, and whose edges describe possible communications between them. This file contains structs and methods that support construction and traversal through computation patterns.
  • mrnesbits.go Methods in this file are called by the root simulation program to read in the simulation model descriptions, and support interactions with the mrnes package.

Copyright 2024 Board of Trustees of the University of Illinois. See the license for details.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ClassMethods map[string]map[string]RespMethod = make(map[string]map[string]RespMethod)

ClassMethods maps the function class name to a map indexed by (string) operation code to get to a pair of functions to handle the entry and exit to the function

View Source 
var ClassMethodsBuilt bool = CreateClassMethods()
View Source 
var CmpPtnInstByID map[int]*CmpPtnInst = make(map[int]*CmpPtnInst)
View Source 
var CmpPtnInstByName map[string]*CmpPtnInst = make(map[string]*CmpPtnInst)

CmpPtnInstByName and CmpPtnInstByID take the the name (alt., id) of an instance of a CompPattern, and associate a pointer to its struct

View Source 
var ExpAttributes map[string][]string
View Source 
var ExpParamObjs []string

ExpParamObjs holds descriptions of the types of objects that are initialized by an exp file for each the attributes of the object that can be tested for to determine whether the object is to receive the configuration parameter, and the parameter types defined for each object type

View Source 
var ExpParams map[string][]string
View Source 
var FuncClassNames map[string]bool = map[string]bool{"connSrc": true, "processPckt": true, "cryptoPckt": true, "cycleDst": true, "chgCP": true, "finish": true}

FuncClassNames needs to have an indexing key for every class of function that might be included in a model.

View Source 
var FuncClasses map[string]FuncClass = make(map[string]FuncClass)

FuncClasses is a map that takes us from the name of a FuncClass

View Source 
var NumIDs int = 0

NumIDs holds value that utility function used for generating unique integer ids on demand

Functions

func BuildExperimentCP 

func BuildExperimentCP(syn map[string]string, useYAML bool, idCounter int, tm TraceManager) (*evtm.EventManager, error)

BuildExperimentCP is called from the module that creates and runs a simulation. Its inputs identify the names of input files, which it uses to assemble and initialize the model (and experiment) data structures. It returns a pointer to an EventManager data structure used to coordinate the execution of events in the simulation.

func CheckDirectories 

func CheckDirectories(dirs []string) (bool, error)

CheckDirectories probes the file system for the existence of every directory listed in the list of files. Returns a boolean indicating whether all dirs are valid, and returns an aggregated error if any checks failed.

func CheckFiles 

func CheckFiles(names []string, checkExistence bool) (bool, error)

CheckFiles probes the file system for permitted access to all the argument filenames, optionally checking also for the existence of those files for the purposes of reading them.

func CheckOutputFiles 

func CheckOutputFiles(names []string) (bool, error)

CheckOutputFiles probles the file system to ensure that every argument filename can be written.

func CheckReadableFiles 

func CheckReadableFiles(names []string) (bool, error)

CheckReadableFiles probles the file system to ensure that every one of the argument filenames exists and is readable

func ClassCreateChgCP 

func ClassCreateChgCP() *chgCP

func ClassCreateConnSrc 

func ClassCreateConnSrc() *connSrc

func ClassCreateCryptoPckt 

func ClassCreateCryptoPckt() *cryptoPckt

func ClassCreateCycleDst 

func ClassCreateCycleDst() *cycleDst

func ClassCreateFinish 

func ClassCreateFinish() *finish

func ClassCreateProcessPckt 

func ClassCreateProcessPckt() *processPckt

func CmpPtnFuncHost 

func CmpPtnFuncHost(cpfi *CmpPtnFuncInst) string

func CmpPtnFuncInstHost 

func CmpPtnFuncInstHost(cpfi *CmpPtnFuncInst) string

CmpPtnFuncInstHost returns the name of the host to which the CmpPtnFuncInst given as argument is mapped.

func CreateClassMethods 

func CreateClassMethods() bool

func EmptyInitFunc 

func EmptyInitFunc(evtMgr *evtm.EventManager, cpFunc any, cpMsg any) any

EmptyInitFunc exists to detect when there is actually an initialization event handler (by having a 'emptyInitFunc' below be re-written to point to something else

func EndRecExec 

func EndRecExec(execID int, time float64) float64

EndRecExec computes the completed execution time of the execution identified, given the ending time, incorporates its statistics into the CmpPtnInst statistics summary

func EnterFunc 

func EnterFunc(evtMgr *evtm.EventManager, cpFunc any, cpMsg any) any

EnterFunc is an event-handling routine, scheduled by an evtm.EventManager to execute and simulate the results of a message arrival to a CmpPtnInst function. The particular CmpPtnInst and particular message are given as arguments to the function. A type-unspecified return is provided.

func ExitFunc 

func ExitFunc(evtMgr *evtm.EventManager, cpFunc any, cpMsg any) any

ExitFunc is an event handling routine that implements the scheduling of messages which result from the completed (simulated) execution of a CmpPtnFuncInst. The CmpPtnFuncInst and the message that triggered the execution are given as arguments to ExitFunc. This routine calls the CmpPtnFuncInst's function that computes the effect of doing the simulation, a routine which (by the CmpPtnFuncInst interface definition) returns a slice of CmpPtnMsgs which are then pushed further along the CompPattern chain.

func FuncExecTime 

func FuncExecTime(cpfi *CmpPtnFuncInst, op string, msg *CmpPtnMsg) float64

FuncExecTime returns the increase in execution time resulting from executing the CmpPtnFuncInst offered as argument, to the message also offered as argument. If the pcktlen of the message does not exactly match the pcktlen parameter of a func timing entry, an interpolation or extrapolation of existing entries is performed.

func GetExpParamDesc 

func GetExpParamDesc() ([]string, map[string][]string, map[string][]string)

GetExpParamDesc returns ExpParamObjs, ExpAttributes, and ExpParams after ensuring that they have been build

func GetExperimentCPDicts 

func GetExperimentCPDicts(syn map[string]string) (*CompPatternDict, *CPInitListDict,
	*SharedStateGroupList, *FuncExecList, *CompPatternMapDict)

GetExperimentCPDicts accepts a map that holds the names of the input files used to define an experiment, creates internal representations of the information they hold, and returns those structs.

func LostCmpPtnMsg 

func LostCmpPtnMsg(evtMgr *evtm.EventManager, context any, msg any) any

LostCmpPtnMsg is scheduled from the mrnes side to report the loss of a comp pattern message

func ReEnter 

func ReEnter(evtMgr *evtm.EventManager, cpFunc any, msg any) any

func RegisterFuncClass 

func RegisterFuncClass(fc FuncClass) bool

RegisterFuncClass is called to tell the system that a particular function class exists, and gives a point to its description. The idea is to register only those function classes actually used, or at least, provide clear separation between classes. Return of bool allows call to RegisterFuncClass as part of a variable assignment outside of a function body

func ReportErrs 

func ReportErrs(errs []error) error

ReportErrs transforms a list of errors and transforms the non-nil ones into a single error with comma-separated report of all the constituent errors, and returns it.

func ReportStatistics 

func ReportStatistics()

func UpdateMsg 

func UpdateMsg(msg *CmpPtnMsg, srcCPID int, srcLabel, msgType, dstLabel string)

func ValidateParameter 

func ValidateParameter(paramObj, attribute, param string) error

ValidateParameter returns an error if the paramObj, attribute, and param values don't make sense taken together within an ExpParameter.

Types

type AlgSpec 

type AlgSpec struct {
	Name   string // e.g., 'aes','des'
	KeyLen []int  // lengths of keys used in measurements represented in the functional timings
}

AlgSpec provides representation of crypto algorithm and key lengths for which we have timing measurements. Used in the CryptoDesc struct below, which can be read by a GUI to align with the crypto algorithms and key lengths that are available

type CPInitList 

type CPInitList struct {
	// name of the Computation Pattern whose Funcs are being initialized
	Name string `json:"name" yaml:"name"`

	// CPType of CP being initialized
	CPType string `json:"cptype" yaml:"cptype"`

	// UseYAML flags whether to interpret the seriaized initialization structure using json or yaml
	UseYAML bool `json:"useyaml" yaml:"useyaml"`

	// State is indexed by Func label, mapping to a serialized representation of a struct
	State map[string]string `json:"state" yaml:"state"`

	// Msgs holds a list of CompPatternMsgs used between Funcs in a CompPattern
	Msgs []CompPatternMsg `json:"msgs" yaml:"msgs"`
}

CPInitList describes configuration parameters for the Funcs of a CompPattern

func CreateCPInitList 

func CreateCPInitList(name string, cptype string, useYAML bool) *CPInitList

CreateCPInitList constructs a CPInitList for an instance of a CompPattern and initializes it with a name and flag indicating whether YAML is used

func ReadCPInitList 

func ReadCPInitList(filename string, useYAML bool, dict []byte) (*CPInitList, error)

ReadCPInitList returns a deserialized slice of bytes into a CPInitList. Bytes are either provided, or are read from a file whose name is given.

func (*CPInitList) AddMsg 

func (cpil *CPInitList) AddMsg(msg *CompPatternMsg) error

AddMsg appends description of a ComPatternMsg to the CPInitList's slice of messages used by the CompPattern. An error is returned if the msg's type already exists in the Msgs list

func (*CPInitList) AddState 

func (cpil *CPInitList) AddState(cp *CompPattern, fnc *Func, state string)

AddState puts a serialized initialization struct in the dictionary indexed by Func label

func (*CPInitList) DeepCopy added in v0.0.3 

func (cpil *CPInitList) DeepCopy() *CPInitList

DeepCopy creates a copy of CPInitList that explicitly copies various complex data structures

func (*CPInitList) WriteToFile 

func (cpil *CPInitList) WriteToFile(filename string) error

WriteToFile serializes the CPInitList and writes it to a file. Output file extension identifies whether serialization is to json or to yaml

type CPInitListDict 

type CPInitListDict struct {
	DictName string `json:"dictname" yaml:"dictname"`

	// indexed by name of comp pattern
	InitList map[string]CPInitList `json:"initlist" yaml:"initlist"`
}

CPInitListDict holds CPInitList structures in a dictionary that may hold prebuilt versions (in which case InitList is indexed by CompPattern type) or is holding init lists for CPs to be part of an experiment, so the CP name is known is used as the key

func CreateCPInitListDict 

func CreateCPInitListDict(name string) *CPInitListDict

CreateCPInitListDict is an initialization constructor. Its output struct has methods for integrating data.

func ReadCPInitListDict 

func ReadCPInitListDict(filename string, useYAML bool, dict []byte) (*CPInitListDict, error)

ReadCPInitListDict deserializes a slice of bytes and returns a CPInitListDict. Bytes are either provided, or are read from a file whose name is given.

func (*CPInitListDict) AddCPInitList 

func (cpild *CPInitListDict) AddCPInitList(cpil *CPInitList) error

AddCPInitList puts a CPInitList into the dictionary

func (*CPInitListDict) RecoverCPInitList 

func (cpild *CPInitListDict) RecoverCPInitList(cptype string, cpname string) (*CPInitList, bool)

RecoverCPInitList returns a copy of a CPInitList from the dictionary

func (*CPInitListDict) WriteToFile 

func (cpild *CPInitListDict) WriteToFile(filename string) error

WriteToFile serializes the CPInitListDict and writes it to a file. Output file extension identifies whether serialization is to json or to yaml

type ChgDesc 

type ChgDesc struct {
	CP, Label, MsgType string
}

func CreateChgDesc 

func CreateChgDesc(cp, label, msgType string) ChgDesc

type CmpPtnFuncInst 

type CmpPtnFuncInst struct {
	InitFunc evtm.EventHandlerFunction // if not 'emptyInitFunc' call this to initialize the function
	InitMsg  *CmpPtnMsg                // message that is copied when this instance is used to initiate a chain of func evaluations

	Label string // an identifier for this func, unique within the instance of CompPattern holding it.

	PtnName string // name of the instantiated CompPattern holding this function
	CPID    int    // id of the comp pattern this func is attached to
	ID      int    // integer identity which is unique among all objects in the MrNesbits model

	State            any // holds string-coded state for string-code state variable names
	InterarrivalDist string
	InterarrivalMean float64
	// contains filtered or unexported fields
}

The CmpPtnFuncInst struct represents an instantiated instance of a function

func (*CmpPtnFuncInst) AddEndMethod 

func (cpfi *CmpPtnFuncInst) AddEndMethod(methodCode string, end evtm.EventHandlerFunction) bool

AddEndMethod includes a customized End method to a previously defined respMethod

func (*CmpPtnFuncInst) AddResponse 

func (cpfi *CmpPtnFuncInst) AddResponse(execID int, resp []*CmpPtnMsg)

AddResponse stores the selected out message response from executing the function, to be released later. Saving through cpfi.Resp[execID] to account for concurrent overlapping executions

func (*CmpPtnFuncInst) AddStartMethod 

func (cpfi *CmpPtnFuncInst) AddStartMethod(methodCode string, start StartMethod) bool

AddStartMethod associates a string response 'name' with a pair of methods used to represent the start and end of the function's execution. The default method for the end method is ExitFunc Return of bool allows call to RegisterFuncClass as part of a variable assignment outside of a function body

func (*CmpPtnFuncInst) GlobalName 

func (cpfi *CmpPtnFuncInst) GlobalName() string

func (*CmpPtnFuncInst) InitMsgParams 

func (cpfi *CmpPtnFuncInst) InitMsgParams(msgType string, msgLen, pcktLen int, rate float64)

type CmpPtnGraph 

type CmpPtnGraph struct {

	// every instance a function has a string 'label', used here to index to
	// data structure that describes it and the connections it has with other funcs
	Nodes map[string]*CmpPtnGraphNode
}

A CmpPtnGraph is the run-time description of a CompPattern

type CmpPtnGraphEdge 

type CmpPtnGraphEdge struct {
	SrcLabel   string
	MsgType    string
	DstLabel   string
	MethodCode string
}

CmpPtnGraphEdge declares the possibility that a function with label srcLabel might send a message of type msgType to the function (in the same CPG) with label dstLabel

func CreateCmpPtnGraphEdge 

func CreateCmpPtnGraphEdge(srcLabel, msgType, dstLabel, methodCode string) *CmpPtnGraphEdge

func (*CmpPtnGraphEdge) EdgeStr 

func (cpge *CmpPtnGraphEdge) EdgeStr() string

type CmpPtnGraphNode 

type CmpPtnGraphNode struct {
	Label    string
	InEdges  []*CmpPtnGraphEdge
	OutEdges []*CmpPtnGraphEdge
}

A CmpPtnGraphNode names a function with its label, and describes the edges for which it is a destination (inEdges) and edges for which it is a source (outEdges)

type CmpPtnInst 

type CmpPtnInst struct {
	ID int // unique id

	Rngs  *rngstream.RngStream
	Graph *CmpPtnGraph // graph describing structure of funcs and edges
	// contains filtered or unexported fields
}

CmpPtnInst describes a particular instance of a CompPattern, built from information read in from CompPatternDesc struct and used at runtime

func (*CmpPtnInst) ExecReport 

func (cpi *CmpPtnInst) ExecReport() []float64

ExecReport reports delay times of completed cmpPtnInst executions

type CmpPtnMsg 

type CmpPtnMsg struct {
	ExecID   int    // initialize when with an initating comp pattern message.  Carried by every resulting message.
	SrcCP    string // name of comp pattern instance from which the message originates
	NxtCP    string // name of comp pattern instance to which the message should be shifted en-route to DstCP
	DstCP    string // name of comp pattern instance to which the message is ultimated directed
	PrevCPID int    // ID of the comp pattern through which the message most recently passed
	Edge     CmpPtnGraphEdge

	// do we need/want CmpHdr?
	CmpHdr EndPts

	MsgType string  // describes function of message
	MsgLen  int     // number of bytes
	PcktLen int     // parameter impacting execution time
	Rate    float64 // when non-zero, a rate limiting attribute that might used, e.g., in modeling IO
	Start   bool    // start the timer
	Payload any     // free for "something else" to carry along and be used in decision logic
}

A CmpPtnMsg struct describes a message going from one CompPattern function to another. It carries ancillary information about the message that is included for referencing.

func CreateCmpPtnMsg 

func CreateCmpPtnMsg(edge CmpPtnGraphEdge, srt, end string, msgType string,
	msgLen int, pcktLen int, rate float64, srcCP, dstCP string,
	payload any, execID int) CmpPtnMsg

CreateCmpPtnMsg is a constructor whose arguments are all the attributes needed to make a CmpPtnMsgEdge. One is created and returned.

type CompPattern 

type CompPattern struct {
	// a model may use a number of instances of CompPatterns that have the same CPType
	CPType string `json:"cptype" yaml:"cptype"`

	// per-instance name of the pattern template
	Name string `json:"name" yaml:"name"`

	// instances of functions indexed by unique-to-pattern label
	Funcs []Func `json:"funcs" yaml:"funcs"`

	// description of edges in Pattern graph
	Edges []CmpPtnGraphEdge `json:"edges" yaml:"edges"`

	// description of external edges in Pattern graph
	ExtEdges map[string][]XCPEdge `json:"extedges" yaml:"extedges"`
}

CompPattern is a directed graph that describes the data flow among functions that implement an end-to-end computation

func CreateCompPattern 

func CreateCompPattern(cmptnType string) *CompPattern

CreateCompPattern is an initialization constructor. Its output struct has methods for integrating data.

func (*CompPattern) AddEdge 

func (cpt *CompPattern) AddEdge(srcFuncLabel, dstFuncLabel string, msgType string, methodCode string,
	msgs *[]CompPatternMsg)

AddEdge creates an edge that describes message flow from one Func to another in the same comp pattern and adds it to the CompPattern's list of edges. Called from code that is building a model, applies some sanity checking

func (*CompPattern) AddExtEdge 

func (cpt *CompPattern) AddExtEdge(srcCP, endCP, nxtCP, srcLabel, dstLabel string, msgType string, methodCode string,
	srcMsgs *[]CompPatternMsg, dstMsgs *[]CompPatternMsg)

AddExtEdge creates an edge that describes message flow from one Func to another in a different computational pattern and adds it to the CompPattern's list of external edges. Perform some sanity checks before commiting the edge

func (*CompPattern) AddFunc 

func (cpt *CompPattern) AddFunc(fs *Func)

AddFunc includes a function specification to a CompPattern

func (*CompPattern) DeepCopy added in v0.0.3 

func (cp *CompPattern) DeepCopy() *CompPattern

DeepCopy creates a copy of CompPattern that explicitly copies various complex data structures

func (*CompPattern) SetName 

func (cpt *CompPattern) SetName(name string)

SetName copies the given name to be the CmpPtn's attribute and saves the name -> CmpPtn mapping in cmptnByName

type CompPatternDict 

type CompPatternDict struct {
	DictName string                 `json:"dictname" yaml:"dictname"`
	Patterns map[string]CompPattern `json:"patterns" yaml:"patterns"`
}

CompPatternDict holds pattern descriptions, is serializable

func CreateCompPatternDict 

func CreateCompPatternDict(name string) *CompPatternDict

CreateCompPatternDict is an initialization constructor. Its output struct has methods for integrating data.

func ReadCompPatternDict 

func ReadCompPatternDict(filename string, useYAML bool, dict []byte) (*CompPatternDict, error)

ReadCompPatternDict returns the transformation of a slice of bytes into a CompPatternDict, reading these from file if necessary.

func (*CompPatternDict) AddCompPattern 

func (cpd *CompPatternDict) AddCompPattern(ptn *CompPattern) error

AddCompPattern amends a CompPattern dictionary with another CompPattern. The prb flag indicates this is saved to a 'pre-built' dictionary from which selected CompPatterns are recovered when building a model. CP names are not created until build time, so the key used to read/write a CompPattern from the Patterns dictionary is the CompPattern cptype when accessing a prb dictionary, and the name otherwise so the CP type is used as a key when true, otherwise the CP name is known and used. If requested, and error is returned if the comp pattern being added is a duplicate.

func (*CompPatternDict) RecoverCompPattern 

func (cpd *CompPatternDict) RecoverCompPattern(cptype string, cpname string) (*CompPattern, bool)

RecoverCompPattern returns a copy of a CompPattern from the dictionary, indexing by type, and applying a name

func (*CompPatternDict) WriteToFile 

func (cpd *CompPatternDict) WriteToFile(filename string) error

WriteToFile serializes the comp pattern, and saves to the named file. Output file extension determines whether serialization is to json or yaml

type CompPatternMap 

type CompPatternMap struct {
	// PatternName identifies the name of the pattern instantiation being mapped
	PatternName string `json:"patternname" yaml:"patternname"`

	// mapping of func labels to hosts. Key is Label attribute of Func
	FuncMap map[string]string `json:"funcmap" yaml:"funcmap"`
}

A CompPatternMap describes how funcs in an instantiated CompPattern are mapped to hosts

func CreateCompPatternMap 

func CreateCompPatternMap(ptnName string) *CompPatternMap

CreateCompPatternMap is a constructor.

func ReadCompPatternMap 

func ReadCompPatternMap(filename string, useYAML bool, dict []byte) (*CompPatternMap, error)

ReadCompPatternMap deserializes a byte slice holding a representation of an CompPatternMap struct. If the input argument of dict (those bytes) is empty, the file whose name is given is read to acquire them. A deserialized representation is returned, or an error if one is generated from a file read or the deserialization.

func (*CompPatternMap) AddMapping 

func (cpm *CompPatternMap) AddMapping(funcLabel string, hostname string, overwrite bool) error

AddMapping inserts into the CompPatternMap a binding of Func label to a host. Optionally, an error might be returned if a binding of that Func has already been made, and is different.

func (*CompPatternMap) WriteToFile 

func (cpm *CompPatternMap) WriteToFile(filename string) error

WriteToFile stores the CompPatternMap struct to the file whose name is given. Serialization to json or to yaml is selected based on the extension of this name.

type CompPatternMapDict 

type CompPatternMapDict struct {
	DictName string                    `json:"dictname" yaml:"dictname"`
	Map      map[string]CompPatternMap `json:"map" yaml:"map"`
}

A CompPatternMapDict holds copies of CompPatternMap structs in a map that is indexed by the PatternName of resident CompPatternMaps 

var CmpPtnMapDict *CompPatternMapDict

func CreateCompPatternMapDict 

func CreateCompPatternMapDict(name string) *CompPatternMapDict

CreateCompPatternMapDict is a constructor. Saves the dictionary name and initializes the map of CompPatternMaps to-be-stored.

func ReadCompPatternMapDict 

func ReadCompPatternMapDict(filename string, useYAML bool, dict []byte) (*CompPatternMapDict, error)

ReadCompPatternMapDict deserializes a byte slice holding a representation of an CompPatternMapDict struct. If the input argument of dict (those bytes) is empty, the file whose name is given is read to acquire them. A deserialized representation is returned, or an error if one is generated from a file read or the deserialization.

func (*CompPatternMapDict) AddCompPatternMap 

func (cpmd *CompPatternMapDict) AddCompPatternMap(cpm *CompPatternMap, overwrite bool) error

AddCompPatternMap includes in the dictionary a CompPatternMap that is provided as input. Optionally an error may be returned if an entry for the associated CompPattern exists already.

func (*CompPatternMapDict) RecoverCompPatternMap 

func (cpmd *CompPatternMapDict) RecoverCompPatternMap(pattern string) (*CompPatternMap, bool)

RecoverCompPatternMap returns a CompPatternMap associated with the CompPattern named in the input parameters. It returns also a flag denoting whether the identified CompPattern has an entry in the dictionary.

func (*CompPatternMapDict) WriteToFile 

func (cpmd *CompPatternMapDict) WriteToFile(filename string) error

WriteToFile stores the CompPatternMapDict struct to the file whose name is given. Serialization to json or to yaml is selected based on the extension of this name.

type CompPatternMsg 

type CompPatternMsg struct {
	// edges in the CompPattern graph are labeled with MsgType, which means that a message across the edge must match in this attribute
	MsgType string `json:"msgtype" yaml:"msgtype"`

	// a message may be a packet or a flow
	IsPckt bool `json:"ispckt" yaml:"ispckt"`

	// PcktLen is a parameter used by some functions to select their execution time.
	// Not the same as the length of the message carrying the packet
	PcktLen int `json:"pcktlen" yaml:"pcktlen"`

	// MsgLen is the total length of the message c
	MsgLen int `json:"msglen" yaml:"msglen"`
}

CompPatternMsg defines the structure of identification of messages that pass between Funcs in a CompPattern. Structures of this sort are transformed by a simulation run into a form that include experiment-defined payloads, and so representation of payload is absent here,

func CreateCompPatternMsg 

func CreateCompPatternMsg(msgType string, pcktLen int, msgLen int) *CompPatternMsg

CreateCompPatternMsg is a constructer.

type CryptoDesc 

type CryptoDesc struct {
	Algs []AlgSpec
}

CryptoDesc is a structure used so that the GUI and simulator can 'see' the same set of crypto algorithms that might be chosen, and have their performance included in the system behavior

func BuildCryptoDesc 

func BuildCryptoDesc(filename string) *CryptoDesc

BuildCryptoDesc scans a given file of timing descriptions, looking for those with a Param == "KeyLength=integer" which are taken to be crypto algortithms and the Param a string-encoded integer description of the key length version

func ReadCryptoDesc 

func ReadCryptoDesc(filename string, useYAML bool, dict []byte) (*CryptoDesc, error)

ReadCryptoDesc deserializes a byte slice holding a representation of an CryptoDesc struct. If the input argument of dict (those bytes) is empty, the file whose name is given is read to acquire them. A deserialized representation is returned, or an error if one is generated from a file read or the deserialization.

func (*CryptoDesc) WriteToFile 

func (cd *CryptoDesc) WriteToFile(filename string) error

WriteToFile stores the CryptoDesc struct to the file whose name is given. Serialization to json or to yaml is selected based on the extension of this name.

type EndPts 

type EndPts struct {
	SrtLabel string
	EndLabel string
}

EndPts carries information on a CmpPtnMsg about where the execution thread started, and holds a place for a destination

type ExpCfg 

type ExpCfg struct {
	// Name is an identifier for a group of [ExpParameters].  No particular interpretation of this string is
	// used, except as a referencing label when moving an ExpCfg into or out of a dictionary
	Name string `json:"expname" yaml:"expname"`

	// Parameters is a list of all the [ExpParameter] objects presented to the simulator for an experiment.
	Parameters []ExpParameter `json:"parameters" yaml:"parameters"`
}

An ExpCfg structure holds all of the ExpParameters for a named experiment

func CreateExpCfg 

func CreateExpCfg(name string) *ExpCfg

CreateExpCfg is a constructor. Saves the offered Name and initializes the slice of ExpParameters.

func ReadExpCfg 

func ReadExpCfg(filename string, useYAML bool, dict []byte) (*ExpCfg, error)

ReadExpCfg deserializes a byte slice holding a representation of an ExpCfg struct. If the input argument of dict (those bytes) is empty, the file whose name is given is read to acquire them. A deserialized representation is returned, or an error if one is generated from a file read or the deserialization.

func (*ExpCfg) AddParameter 

func (expcfg *ExpCfg) AddParameter(paramObj, attribute, param, value string) error

AddParameter accepts the four values in an ExpParameter, creates one, and adds to the ExpCfg's list. Returns an error if the parameters are not validated.

func (*ExpCfg) WriteToFile 

func (expcfg *ExpCfg) WriteToFile(filename string) error

WriteToFile stores the ExpCfg struct to the file whose name is given. Serialization to json or to yaml is selected based on the extension of this name.

type ExpCfgDict 

type ExpCfgDict struct {
	DictName string            `json:"dictname" yaml:"dictname"`
	Cfgs     map[string]ExpCfg `json:"cfgs" yaml:"cfgs"`
}

An ExpCfgDict is a dictionary that holds ExpCfg objects in a map indexed by their Name.

func CreateExpCfgDict 

func CreateExpCfgDict(name string) *ExpCfgDict

CreateExpCfgDict is a constructor. Saves a name for the dictionary, and initializes the slice of ExpCfg objects

func ReadExpCfgDict 

func ReadExpCfgDict(filename string, useYAML bool, dict []byte) (*ExpCfgDict, error)

ReadExpCfgDict deserializes a byte slice holding a representation of an ExpCfgDict struct. If the input argument of dict (those bytes) is empty, the file whose name is given is read to acquire them. A deserialized representation is returned, or an error if one is generated from a file read or the deserialization.

func (*ExpCfgDict) AddExpCfg 

func (ecd *ExpCfgDict) AddExpCfg(ec *ExpCfg, overwrite bool) error

AddExpCfg adds the offered ExpCfg to the dictionary, optionally returning an error if an ExpCfg with the same Name is already saved.

func (*ExpCfgDict) RecoverExpCfg 

func (ecd *ExpCfgDict) RecoverExpCfg(name string) (*ExpCfg, bool)

RecoverExpCfg returns an ExpCfg from the dictionary, with name equal to the input parameter. It returns also a flag denoting whether the identified ExpCfg has an entry in the dictionary.

func (*ExpCfgDict) WriteToFile 

func (ecd *ExpCfgDict) WriteToFile(filename string) error

WriteToFile stores the ExpCfgDict struct to the file whose name is given. Serialization to json or to yaml is selected based on the extension of this name.

type ExpParameter 

type ExpParameter struct {
	// Type of thing being configured
	ParamObj string `json:"paramObj" yaml:"paramObj"`

	// attribute identifier for this parameter
	Attribute string `json:"attribute" yaml:"attribute"`

	// ParameterType, e.g., "Bandwidth", "WiredLatency", "CPU"
	Param string `json:"param" yaml:"param"`

	// string-encoded value associated with type
	Value string `json:"value" yaml:"value"`
}

An ExpParameter struct describes an input to experiment configuration at run-time. It specified

  • ParamObj identifies the kind of thing being configured : Switch, Router, Host, Interface, or Network
  • Attribute identifies a class of objects of that type to which the configuration parameter should apply. May be "*" for a wild-card, may be "name%%xxyy" where "xxyy" is the object's identifier, may be a comma-separated list of other attributes, documented [here]

func CreateExpParameter 

func CreateExpParameter(paramObj, attribute, param, value string) *ExpParameter

CreateExpParameter is a constructor. Completely fills in the struct with the ExpParameter attributes.

type ExtCmpPtnGraphEdge 

type ExtCmpPtnGraphEdge struct {
	SrcCP string
	CPGE  CmpPtnGraphEdge
}

type Func 

type Func struct {
	// identifies function, e.g., encryptRSA, used to look up execution time
	Class string `json:"class" yaml:"class"`

	// particular name given to function instance within a CompPattern
	Label string `json:"label" yaml:"label"`
}

A Func represents a function used within a CompPattern. Its 'Label' attribute is an identifier for an instance of the Func that is unique among all Funcs that make up a CompPattern which uses it, and the Class attribute is an identifier used when Func describes are stored in a dictionary before being copied and assembled as part of CompPattern construction. Class typically describes the computation the Func represents.

func CreateFunc 

func CreateFunc(class, funcLabel string) *Func

CreateFunc is a constructor for a Func. All parameters are given:

  • Class, a string identifying what instances of this Func do. Like a variable type.
  • FuncLabel, a unique identifier (within an instance of a CompPattern) of an instance of this Func

type FuncClass 

type FuncClass interface {
	FuncClassName() string
	CreateState(string, bool) any
	InitState(*CmpPtnFuncInst, string, bool)
}

A FuncClass represents the methods used to simulate the effect of executing a function, different types of input generate different types of responses, so we use a map whose key selects the start, end pair of methods

type FuncExecDesc 

type FuncExecDesc struct {
	Identifier string  `json:"identifier" yaml:"identifier"`
	Param      string  `json:"param" yaml:"param"`
	Hardware   string  `json:"processortype" yaml:"processortype"`
	PcktLen    int     `json:"pcktlen" yaml:"pcktlen"`
	ExecTime   float64 `json:"exectime" yaml:"exectime"`
}

A FuncExecDesc struct holds a description of a function timing. ExecTime is the time (in seconds), attributes it depends on are 

 Identifier - a unique name for this func call
 Param - additional information, e.g., key length for crypto
	Hardware - the CPU,
	PcktLen - number of bytes in data packet being operated on

type FuncExecList 

type FuncExecList struct {
	// ListName is an identifier for this collection of timings
	ListName string `json:"listname" yaml:"listname"`

	// Times key is an identifier for the function.
	// Value is list of function times for that type of function
	Times map[string][]FuncExecDesc `json:"times" yaml:"times"`
}

A FuncExecList holds a map (Times) whose key is the class of a Func, and whose value is a list of FuncExecDescs associated with all Funcs of that class

func CreateFuncExecList 

func CreateFuncExecList(listname string) *FuncExecList

CreateFuncExecList is an initialization constructor. Its output struct has methods for integrating data.

func ReadFuncExecList 

func ReadFuncExecList(filename string, useYAML bool, dict []byte) (*FuncExecList, error)

ReadFuncExecList deserializes a byte slice holding a representation of an FuncExecList struct. If the input argument of dict (those bytes) is empty, the file whose name is given is read to acquire them. A deserialized representation is returned, or an error if one is generated from a file read or the deserialization.

func (*FuncExecList) AddTiming 

func (fel *FuncExecList) AddTiming(identifier, param, hardware string,
	pcktLen int, execTime float64)

AddTiming takes the parameters of a FuncExecDesc, creates one, and adds it to the FuncExecList

func (*FuncExecList) WriteToFile 

func (fel *FuncExecList) WriteToFile(filename string) error

WriteToFile stores the FuncExecList struct to the file whose name is given. Serialization to json or to yaml is selected based on the extension of this name.

type GlobalFuncInstID 

type GlobalFuncInstID struct {
	CmpPtnName string
	Label      string
}

GlobalFuncInstID is a global identifier for a function, naming the CmpPtn that holds it and its label within that CmpPtn

type InEdge 

type InEdge struct {
	SrcLabel   string `json:"srclabel" yaml:"srclabel"`
	MsgType    string `json:"msgtype" yaml:"msgtype"`
	MethodCode string `json:"methodcode" yaml:"methodcode"`
}

An InEdge describes the source Func of an incoming edge, the type of message it carries, and the method code flagging what code should execute as a result

func InEdgeMsg 

func InEdgeMsg(cmp *CmpPtnMsg) InEdge

InEdgeMsg returns the InEdge structure embedded in a CmpPtnMsg

type NetSimPortal 

type NetSimPortal interface {
	HostCPU(string) string
	EnterNetwork(*evtm.EventManager, string, string, int, int, float64, any,
		any, evtm.EventHandlerFunction, any, evtm.EventHandlerFunction) any
}

NetSimPortal provides an interface to network simulator in the mrnes package. mrnes does not import mrnesbits (to avoid circular imports). However, code in mrnesbits can call a function in mrnes that returns a pointer to a structure that satisfies the NetSimPortal interface.

type OutEdge 

type OutEdge struct {
	MsgType  string `json:"msgtype" yaml:"msgtype"`
	DstLabel string `json:"dstlabel" yaml:"dstlabel"`
}

An OutEdge describes the destination Func of an outbound edge, and the type of message it carries.

type RespMethod 

type RespMethod struct {
	Start StartMethod
	End   evtm.EventHandlerFunction
}

RespMethod associates two RespFunc that implement a function's response, one when it starts, the other when it ends

type SharedStateGroup 

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

SharedStateGroup gathers descriptions of functions that share the same state information, even across CmpPtn boundaries

func CreateSharedStateGroup 

func CreateSharedStateGroup(name string, class string) *SharedStateGroup

CreateSharedStateGroup is a constructor

func (*SharedStateGroup) AddInstance 

func (ssg *SharedStateGroup) AddInstance(cmpPtnName, label string)

AddInstance appends a global function description to a shared state group, but makes sure that it does not exist already in that group

func (*SharedStateGroup) AddState 

func (ssg *SharedStateGroup) AddState(stateStr string)

AddState gives a shared state group a serialized common state

type SharedStateGroupList 

type SharedStateGroupList struct {
	// UseYAML flags whether to interpret the seriaized state using json or yaml
	UseYAML bool               `json:"useyaml" yaml:"useyaml"`
	Groups  []SharedStateGroup `json:"groups" yaml:"groups"`
}

SharedStateGroupList holds all the shared state groups defined, for inclusion in a shared state description file

func CreateSharedStateGroupList 

func CreateSharedStateGroupList(yaml bool) *SharedStateGroupList

CreateSharedStateGroupList is a constructor

func ReadSharedStateGroupList 

func ReadSharedStateGroupList(filename string, useYAML bool, dict []byte) (*SharedStateGroupList, error)

ReadSharedStateGroupList returns a deserialized slice of bytes into a SharedStateGroupList. Bytes are either provided, or are read from a file whose name is given.

func (*SharedStateGroupList) AddSharedStateGroup 

func (ssgl *SharedStateGroupList) AddSharedStateGroup(ssg *SharedStateGroup)

AddSharedStateGroup includes an offered state group the the list, but checks that there is not already one there with the same name and class

func (*SharedStateGroupList) WriteToFile 

func (ssgl *SharedStateGroupList) WriteToFile(filename string) error

WriteToFile serializes the SharedStateGroupList and writes it to a file. Output file extension identifies whether serialization is to json or to yaml

type StartMethod 

type StartMethod func(*evtm.EventManager, *CmpPtnFuncInst, string, *CmpPtnMsg)

StartMethod gives the signature of functions called to implement a function's entry point

type TraceManager 

type TraceManager interface {

	// at creation a flag is set indicating whether the trace manager will be active
	Active() bool

	// add a trace event to the manager
	AddTrace(vrtime.Time, int, int, int, string, bool, float64)

	// include an id -> (name, type) pair in the trace manager dictionary
	AddName(int, string, string)

	// save the trace to file (if active) and return flag indicating whether file creatation actually happened
	WriteToFile(string) bool
}

The TraceManager interface helps integrate use of the mrnes functionality for managing traces in the mrnesbits package

type XCPEdge 

type XCPEdge struct {
	SrcCP      string
	EndCP      string
	NxtCP      string
	SrcLabel   string
	DstLabel   string
	MsgType    string
	MethodCode string
}

XCPEdge describes an edge between different CmpPtns. 

These are always rooted in a function of the chgCP class,

where they are organized in a map whose index is the ultimate target CP for a message. The attribute is an XCPEdge, which specifies (a) the identity of the next CmpPtn, (b) the identity of the function to receive the message, (c) the type of the X-CP message, and (d) the methodCode for the function method to be executed. Note that this structure limits one XCPEdge per chgCP instance per target CP.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.