Guest APIs

Guest APIs are the guest side APIs (your program) of the built-in services and parigot proper.

lib

import "github.com/iansmith/parigot/api/guest/queue/lib"

Index

func FindOrCreateQueue

func FindOrCreateQueue(ctx context.Context, queueHandle queue.Client, name string) *future.Base[queue.QueueId]

FindOrCreateQueue gets a queue by name, creating it if necessary. The return value will be the queue.QueueIdZeroValue if there was any error, which is a bit dodgy.

syscall

import "github.com/iansmith/parigot/api/guest/syscall"

Index

func BindMethod

func BindMethod(in *syscall.BindMethodRequest) (*syscall.BindMethodResponse, syscall.KernelErr)

func BindMethod_

func BindMethod_(int32, int32, int32, int32) int64

BindMethod is the way that a particular service gets associated with a given method id. This is normally not needed by user code because the generated code for any service will call this automatically.

func BindMethod(*syscall.BindMethodRequest) *syscall.BindMethodResponse

func BlockUntilCall

func BlockUntilCall(in *syscall.BlockUntilCallRequest) (*syscall.BlockUntilCallResponse, error)

func BlockUntilCall_

func BlockUntilCall_(int32, int32) int32

BlockUntilCall is used to block a process until a request is received from another process. Even when all the “processes” are in a single process for debugging, the BlockUntilCall is for the same purpose.

func BlockUntilCall(*syscall.BlockUntilCallRequest) *syscall.BlockUntilCallResponse

func ClientSide

func ClientSide[T proto.Message, U proto.Message](ctx context.Context, t T, u U, fn func(int32, int32, int32, int32) int64) (outU U, outId int32, signal bool)

ClientSide does the marshalling and unmarshalling needed to read the T given, write the U given, and return the KernelErrId properly. It does these manipulations so you can call a lower level function that is implemented by the host. The final bool is a meta indicator about if we detected a crash and the client side of the program should exit.

func Dispatch

func Dispatch(inPtr *syscall.DispatchRequest) (*syscall.DispatchResponse, syscall.KernelErr)

func Dispatch_

func Dispatch_(int32, int32, int32, int32) int64

Dispatch is the primary means that a caller can send an RPC message. If you are in local development mode, this call is handled by the kernel itself, otherwise it implies a remote procedure call. This method checks the returned response for errors. If there are errors inside the result they are pulled out and returned in the error parameter. Thus if the error parameter is nil, the Dispatch() occurred successfully. This is code that runs on the WASM side.

func Exit

func Exit(err int32) (*syscall.ExitResponse, syscall.KernelErr)

func Exit_

func Exit_(int32, int32, int32, int32) int64

Exit is called from the WASM side to cause the WASM program to exit. This is implemented by causing the WASM code to panic and then using recover to catch it and then the program is stopped and the kernel will marke it dead and so forth.

func Export

func Export(inPtr *syscall.ExportRequest) (*syscall.ExportResponse, syscall.KernelErr)

func Export_

func Export_(int32, int32, int32, int32) int64

Export is a declaration that a service implements a particular interface. This is not needed by most user code that will use queue.ExportQueueServiceOrPanic() to export itself as the queue service.

func Launch

func Launch(inPtr *syscall.LaunchRequest) (*syscall.LaunchResponse, syscall.KernelErr)

func Launch_

func Launch_(int32, int32, int32, int32) int64

Run is starts a service (or a guest application) running. Note that this may not return immediately and may fail entirely. For most user code this is not used because user code usually uses file.MustFileServiceRun() to block service File until it is cleared to run.

func Locate

func Locate(inPtr *syscall.LocateRequest) (*syscall.LocateResponse, syscall.KernelErr)

func Locate_

func Locate_(int32, int32, int32, int32) int64

Locate is the means of aquiring a handle to a particular service. Most users will not want this interface, but rather will use the auto generated method LocateFooOrPanic() for getting an initial handle the Foo service.

func Locate(*syscall.LocateRequest) *syscall.LocateResponse

func ManufactureGuestContext

func ManufactureGuestContext(fn string) context.Context

Manufacture context is used to setup the context for a given state that makes sense for this, the Guest side of the wire. You pass the name of the function you are constructing this in.

func MustBindMethodName

func MustBindMethodName(in *syscall.BindMethodRequest) id.MethodId

func MustSatisfyWait

func MustSatisfyWait(ctx context.Context, sid id.ServiceId)

MustSatisfyWait is a convenience wrapper around creating a RunRequest and using the Run syscall. MustSatisfyWait is a better name for what goes on in the course of a Run() call.

func ReadOne

func ReadOne(in *syscall.ReadOneRequest) (*syscall.ReadOneResponse, syscall.KernelErr)

func ReadOne_

func ReadOne_(int32, int32, int32, int32) int64

ReadOne checks to see if any of the service/method pairs have been called. Timeouts of negative values (forever) and 0 (instant check) are legal.

func Register

func Register(inPtr *syscall.RegisterRequest) (*syscall.RegisterResponse, syscall.KernelErr)

func Register_

func Register_(int32, int32, int32, int32) int64

Register should be called before any other services are Required, Exported, or Located.

func Require

func Require(inPtr *syscall.RequireRequest) (*syscall.RequireResponse, syscall.KernelErr)

func Require_

func Require_(int32, int32, int32, int32) int64

Require is a declaration that a service needs a particular interface. This is not needed by most user code that will use queue.ImpleQueueServiceOrPanic() to import the queue service.

func ReturnValue

func ReturnValue(in *syscall.ReturnValueRequest) syscall.KernelErr

func ReturnValue_

func ReturnValue_(int32, int32, int32, int32) int64

ReturnValue is for providing return values for calls that have been made on the local service.

test

import "github.com/iansmith/parigot/api/guest/test"

Index

lib

import "github.com/iansmith/parigot/lib/go"

Index

func AddServerReturn

func AddServerReturn(fut future.Method[proto.Message, int32])

AddServerReturn is called to register a server side function result as a future.

func CompleteCall

func CompleteCall(ctx context.Context, cid id.CallId, result *anypb.Any, resultErr int32) syscall.KernelErr

CompleteCall is called from the CallOne handler to cause a prior dispatch call to be completed. The matching is done based on the cid.

func CurrentHostId

func CurrentHostId() id.HostId

func ExpireMethod

func ExpireMethod(ctx context.Context)

ExpireMethod() checks the internal list of guest side futures that have no call id associated with them. These futures come about when a implementation of a server function returns a future that is not completed. This future likely exists because the implementation of the server function called another service and the result of the server function thus cannot be calculated immediately. When the call is completed, the Success or Failure functions will be called on the original future. This function exists to maintain a list so that we can expire and cancel futures that have waiting longer than the timeout time.

func Export1

func Export1(pkg, name string) (*syscall.ExportResponse, syscall.KernelErr)

Export1 is a thin wrapper over syscall.Export so it’s easy to export things by their name. This is used by the code generator primarily.

func FlagParseCreateEnv

func FlagParseCreateEnv()

func Getenv

func Getenv(envvar string) string

This is a workalike for os.Getenv()

func LookupEnv

func LookupEnv(envvar string) (string, bool)

This is a workalike for os.LookupEnv(). It can be used to differentiate an empty, but set, environment variable from the an enviroment variable that is simply not present.

func MatchCompleter

func MatchCompleter(cid id.CallId, comp future.Completer)

MatchCompleter is a utility for adding a new cid and completer to the tables used to look up the location where response values should be sent.

func MustInitClient

func MustInitClient(ctx context.Context, requirement []MustRequireFunc) id.ServiceId

MustInitClient is for clients only. In other words, you should only use this function if you do not implement services, just use them. A common case of this is a demo program or a program that performs a one off task. This function wraps MustRegisterClient and panics if things go wrong.

func MustRegisterClient

func MustRegisterClient(ctx context.Context) id.ServiceId

MustRegisterClient should be used by the “main” function of a client program that is not service itself, in other words it is a client only. If you are a service, you should use the automagically generated code MustRegister<BLAH>().

func MustRunClient

func MustRunClient(ctx context.Context, timeoutInMillis int32) syscall.KernelErr

func Require1

func Require1(pkg, name string, source id.ServiceId) (*syscall.RequireResponse, syscall.KernelErr)

Require1 is a thin wrapper over syscall.Require so it’s easy to require things by their name. This is used by the code generator primarily.

type Backgrounder

Backgrounder is an interface that can be implemented by types that want to get period background calls when the latest attempt to receive a call has timed out. Note that when the background is actually running (in Background) their are no attempts to retreive method calls on this service.

type Backgrounder interface {
    Background(context.Context)
}

type FuncAnyIO

FuncAnyIO is the type of the guest-side functions that implement the set and tear down of method implementations in a server. If a method fleazil is defined on a service, it will have FuncAnyIO wrapper that unmarshals input parameters and marshals the return value.

type FuncAnyIO func(*anypb.Any) future.Method[*anypb.Any, int32]

type MustRequireFunc

MustRequireFunc is the type of the functions that are created by the code generator from protobuf definitions of the form MustRequireXXXX(). These are used in the function RunXXXX() to indicate required services (dependencies).

type MustRequireFunc func(context.Context, id.ServiceId)

type ServiceMethodMap

ServiceMethodMap is the data structure that provides conversions between a service/method pair and their variants. A service or method can be converted to a string with their String() method and this method can convert that string back to the appropriate service or method. The ServiceMethodMap can also convert between the human readable names of services and methods and their appropriate Ids. It contains a mapping from a service/method pair to a FuncAnyIO that is the guest-side implementation of the method. Finally, it allows particular methods to be enabled and disabled so they will not be used when generating the list of pairs for a call to ReadOne().

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

func NewServiceMethodMap

func NewServiceMethodMap() *ServiceMethodMap

func (*ServiceMethodMap) AddServiceMethod

func (s *ServiceMethodMap) AddServiceMethod(sid id.ServiceId, mid id.MethodId, serviceName, methodName string, fn future.Invoker)

AddServiceMethod is called when a new method has been bound. This method creates various data structures needed to be able to look up the service and method later, as well as find the appropriate Invoker associated with pair. Note that the Invoker may be nil when the function is not available in this address space and any caller must use Dispatch().

func (*ServiceMethodMap) Call

func (s *ServiceMethodMap) Call() []*syscall.ServiceMethodCall

Pair returns a list of Service/Method pairs suitable for use in a ReadOneRequest. Particular elements of the map can be omitted or included with Disable and Enable.

func (*ServiceMethodMap) Disable

func (s *ServiceMethodMap) Disable(sid id.ServiceId, mid id.MethodId)

Disable “turns off” a service/method pair within this map. This pair will not appear in results of Pair() until Enable is called for this pair. If the values of this pair of ids does not correspond to a real pair that is known to the service, this call is ignored. Disable can be useful in production situations where you want disable methods on an object that are only for testing.

func (*ServiceMethodMap) Enable

func (s *ServiceMethodMap) Enable(sid id.ServiceId, mid id.MethodId)

Enable “turns on” a given service/method pair within the map. Thus the pair will be returned as part of the Pair() result. If the pair of these ids is not found, this call is ignored. Enable can be useful in testing situations where you want enable methods on an object that are only for testing.

func (*ServiceMethodMap) Func

func (s *ServiceMethodMap) Func(sid id.ServiceId, mid id.MethodId) future.Invoker

Func returns the FuncAnyIO object associated with the sid and mid pair. If either sid or mid cannot be found, it returns nil.

func (*ServiceMethodMap) Len

func (s *ServiceMethodMap) Len() int

Len returns the number of known methods in this ServiceMethodMap

func (*ServiceMethodMap) MethodIdToName

func (s *ServiceMethodMap) MethodIdToName(mid id.MethodId) string

MethodIdToName is used to find a method given a particular service id. This function returns "" if either the service or the method cannot be found. This does not require a service id because method ids are unique.

func (*ServiceMethodMap) MethodNameToId

func (s *ServiceMethodMap) MethodNameToId(sid id.ServiceId, methodName string) id.MethodId

MethodNameToId is used to find a method by name, given a particular service id. This function returns the value MethodIdZeroValue if either the service or the method cannot be found.

client

import "github.com/iansmith/parigot/lib/go/client"

Index

type BaseService

BaseService is a type that is used for all client (call origin) side implementations. This includes any client in the guest codespace. This object primarily just receives message call requests and this type sends it to the kernel.

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

func LocateDynamic

func LocateDynamic(ctx context.Context, protoPkg, serviceName string, calledBy id.ServiceId) (*BaseService, syscall.KernelErr)

LocateDynamic is an important interface to the infrastructure’s knowlege about the types and methods of services. This method takes a package and a service name and returns a client side proxy that can call all the methods that the system knows about for the given service. This is usually used by the code generate to then wrap method declarations around to give the resulting client object an API that is more what is expected. However, it can be used “uncooked” and its methods called via Dispatch(). This is the only mechanism by which you can call methods on services that are not known at compile time, e.g. looking up a service by package and name, then and calling methods on the service entirely by using strings.

func NewBaseService

func NewBaseService(ctx context.Context, id id.ServiceId, sm *lib.ServiceMethodMap) *BaseService

NewBaseService creates.

func (*BaseService) Dispatch

func (c *BaseService) Dispatch(method id.MethodId, param proto.Message) (id.CallId, syscall.KernelErr)

Dispatch is called by every client side “method” on the client side service. This funciton is the one that make a system call to the kernel and prepares for handling the result.

func (*BaseService) MethodIdByName

func (c *BaseService) MethodIdByName(str string) (id.MethodId, bool)

func (*BaseService) ServiceId

func (c *BaseService) ServiceId() id.ServiceId

func (*BaseService) ServiceMethodMap

func (c *BaseService) ServiceMethodMap() *lib.ServiceMethodMap

func (*BaseService) String

func (c *BaseService) String() string

String() returns a useful string for debugging a client side service. This includes all the known methods for the service.

future

import "github.com/iansmith/parigot/lib/go/future"

The concept of a “future” is important in parigot. For any programming language that can create closures, this concept allows one to write parigot programs that are singly-threaded. A future is similar to a promise in Javascript and related languages.

A future represents a computation that has not completed yet, but is expected to be completed in the near future. A future is “completed” when its value or values are known because the computation that was being waited on has finished. In the case of parigot, frequently that computation has been completed by another process or another process on another machine.

parigot offers two types of futures, Base and Method. Base futures represent a single value and the result can be acted upon in the method Handle(). Base futures are used when a single value, such as bool, is being computed but it is not completed as-of yet. The method Ready() on a service returns a Base future to inidicate if a service can start or not (bool).

Method futures are a special case of future that is used frequently in parigot. Method futures represent the value of a remote method call that has not completed yet. The value of a method call is computed by some other program and then set to indicate the value(s) of that this method has returned. In the simple case of all the programs being run in a single address space (process) this other program is another WASM binary executing inside the same WASM engine.

Index

type AllFuture

AllFuture is the underlying Future type for a call to the All() function. As with Base and Method, this future queues all the calls to Success() and Failure().

type AllFuture[T proto.Message, U ErrorType] struct {
    // contains filtered or unexported fields
}

func All

func All[T proto.Message, U ErrorType](dep ...*Method[T, U]) *AllFuture[T, U]

All waits for all its dependent futures to complete and if they all complete successfully, it calls the Success function, otherwise the index of a failing future is sent to the Failure() method.

func NewAllFuture

func NewAllFuture[T proto.Message, U ErrorType](dep []*Method[T, U]) *AllFuture[T, U]

func (*AllFuture[T, U]) AllDependent

func (a *AllFuture[T, U]) AllDependent() []*Method[T, U]

func (*AllFuture[T, U]) Failure

func (a *AllFuture[T, U]) Failure(fn func(int))

func (*AllFuture[T, U]) Success

func (a *AllFuture[T, U]) Success(fn func())

type Base

Base[T] represents a future computation resulting in a T. This is useful for simple value types such bool and int64. It only has one user-visible method which is Handle() and that is used to set a handler for when the value of type T actually arrives.

type Base[T any] struct {
    // contains filtered or unexported fields
}

func NewBase

func NewBase[T any]() *Base[T]

NewBase returns a new pointer at a Base[T]. The value will be the zero value of T and the future is not marked completed. If you wish to make the zero value the result of the future you should use NewBaseWithValue or Set().

func NewBaseWithValue

func NewBaseWithValue[T any](t T) *Base[T]

NewBaseWithValue creates a new pointer a Base[T] with the given value and with future marked as completed.

func (*Base[T]) Cancel

func (f *Base[T]) Cancel()

Cancel causes the future’s state to be cleared and the future to be marked completed. Any calls to Set() that occur after Cancel() and before any other calls to Handle() will have no effect. Any existing chain of Handle() functions will be removed from the future by Cancel(). Since the call to Cancel() marks the

func (*Base[T]) Completed

func (f *Base[T]) Completed() bool

Completed returns true if all the Handle() functions on this future have run. Note that is can be changed by the addition of new Handle() functions via Handle().

func (*Base[T]) Handle

func (f *Base[T]) Handle(fn func(T))

func (*Base[T]) HandleLater

func (f *Base[T]) HandleLater(fn func(T))

HnadleLater is used in the rare instance can where you have a future that has possibly completed all of its Handle() functions and you wish to delay the excution of fn until the next Set() call. Note that the default behavior of Handle() would be to run fn immediately, and thus you only need this function if you call must Set multiple times on the same future with the possibility that is already completed.

func (*Base[T]) Set

func (f *Base[T]) Set(t T) bool

Set causes the future it is called on be marked as completed with the given value. This will cause all registered Handle() functions to run. Set can be called multiple times and the effect is that only the as yet incomplete Handle() functions will be executed as a result. These previously unexecuted handle functions will be marked and and have their result values set to the value of *this* call to set. It is thus possible that different handlers will run with different values as their parameters. Set returns true if any Handle functions were run.

func (*Base[T]) String

func (f *Base[T]) String() string

Strings returns a human-friendly representation of this Base futuer. It returns if the future is complete or not.

type Completer

Completer is the interface that means that a given type can be “completed” at a later time. This is used only for Methods.

type Completer interface {
    CompleteMethod(ctx context.Context, msg proto.Message, resultErr int32) syscall.KernelErr
    Success(func(proto.Message))
    Failure(func(int32))
}

type ErrorType

type ErrorType interface {
    // contains filtered or unexported methods
}

type Invoker

Invoker is the interface that means that a given type be run as an implementation of a function..

type Invoker interface {
    // Invoke has to do the work to unmarshal the msg because it knows
    // the specific type to use whereas the caller does not.
    Invoke(ctx context.Context, msg *anypb.Any) Completer
}

type Method

Method is a special type of future that is used frequently in parigot because all the methods of a service, and the methods of clients that use that same service, must return this type. It has the special behavior that when CompleteMethod is called on this Method, the error value is compared to zero and this determines if the Success (error value is 0) or Failure (error is not 0) handler function is called.

It is thus impossible to have a Method that can behave in a failed way (call to Failure) based on the return value being 0. In this case, use a Base[int32], as parigot does.

type Method[T proto.Message, U ErrorType] struct {
    // contains filtered or unexported fields
}

func NewMethod

func NewMethod[T proto.Message, U ErrorType](resolve func(T), reject func(U)) *Method[T, U]

NewMethod return as method future with two types given. The T type (first) must be a proto.Message and typically is a Response object from a previous call to the Method. The error value, U, is typically a named enum that is used for error signaling by the method called.

func (*Method[T, U]) Cancel

func (m *Method[T, U]) Cancel()

Cancel causes a future to be marked completed and also to remove any and all possible calls to a Sucess() or Failure() function later. This enforces that a Cancel() is permanent, even if the future is “completed” later. Calling Cancel() on an already completed future will be ignored.

func (*Method[T, U]) CompleteMethod

func (f *Method[T, U]) CompleteMethod(ctx context.Context, result T, resultErr U)

CompleteMethod is called to indicate that the outcome, or value, of the future is now known. This method is typically called by the infrastructure of Parigot, but it can be useful to call this method directly in tests. Calling this method on completed Method future will be ignored.

func (*Method[T, U]) Completed

func (f *Method[T, U]) Completed() bool

Completed returns true if this method has already completed.

func (*Method[T, U]) Failure

func (f *Method[T, U]) Failure(fn func(U))

Failure provides a function to be called if the Method completion supplies a non zero error value. Calling failure on a completed Method that had an error causes the given function to run immediately.

func (*Method[T, U]) String

func (f *Method[T, U]) String() string

String() returns a human-friendly version of this Method future. It shows it is resolved and if so, if the completion was an error.

func (*Method[T, U]) Success

func (f *Method[T, U]) Success(fn func(T))

Success provides a function to be called if the Method returns a success. Calling Success() on an already completed method causes the code supplied in the success method to be run immediately if the future was resolved successfully.

func (*Method[T, U]) ValueErr

func (f *Method[T, U]) ValueErr() U

ValueErr may not do what you expect: This function does not force the world to stop and wait for the Error in question to be received. It can only be trusted when the function Completed() returns true and the function WasSuccess() returns false. It returns the value of the error on a completed Method.

func (*Method[T, U]) ValueResponse

func (f *Method[T, U]) ValueResponse() T

ValueResponse may not do what you expect: This function does not force the world to stop and wait for the Response in question to be received. It can only be trusted when the function Completed() returns true and the function WasSuccess() returns true. This function returns the value of a response (type T) on a completed method

func (*Method[T, U]) WaitingId

func (m *Method[T, U]) WaitingId() string

WaitingId is useful only to the go client side library. The WaitingId is a repurposing of the CallId to create a key value, a string, for use in a map, since Method[T,U] is not a valid key type in go.

func (*Method[T, U]) WasSuccess

func (f *Method[T, U]) WasSuccess() bool

WasSuccess returns true if the Method is completed and finished as a sucess. Before a Method is completed, it returns false.

apishared

import "github.com/iansmith/parigot/api/shared"

Index

Constants

EntryPointSymbol is what should be used to start up a ready instance. Note that we are turning off the instantiation’s normal call to start so that we can control the startup and its entry point.

const EntryPointSymbol = "_start"

ExpectedStackDumpSize is used to allocate space so that stack trace can be placed in it, then read back line by line.

const ExpectedStackDumpSize = 4096 * 2


const FileServiceMaxBufSize = 2048


const FileServicePathPrefix = "/parigot/app/"

GuestReceiveBufferSize is the maximum amount data that the guest expects to read in a response back from the server. Usually the send side is known apriori.

const GuestReceiveBufferSize = WasmPageSize

WasmPageSize is the size of a memory page in wasm. I believe this is dictated by the spec.

const WasmPageSize = 4096

Variables

The amount of time we will wait for a function call to be completed.

var FunctionTimeoutInMillis = int64(3000)

KoopmanTable is the `crc32.Koopman` data in a table ready to use for CRC32 computations.

var KoopmanTable = crc32.MakeTable(crc32.Koopman)

In parigot the 8 byte magic value, when needed, is the date of the french and us revolutions, in hex.

var MagicStringOfBytes = uint64(0x1789071417760704)

ReadBuffer is the maximum amount of data you can expect to receive in single read call with files or the network.

var ReadBufferSize = 8192

WasmIs32Bit is true on a 32 bit wasm implementation

var WasmIs32Bit bool // init function

WasmWith is the size of a uintptr for the wasm virtual machine.

var WasmWidth = int32(unsafe.Sizeof(uintptr(0))) // in bytes

id

import "github.com/iansmith/parigot/api/shared/id"

Index

type CallId

type CallId IdRoot[DefCall]

func CallIdEmptyValue

func CallIdEmptyValue() CallId

func CallIdFromPair

func CallIdFromPair(high, low uint64) CallId

FromPair is probably not something you want to use unless you are pulling values from external storage or files. If you pulling values from the network, use the Marshal() ad Unmarshal() functions to work with Ids. Absolutely no checking is done on the values provided, so much caution is advised.

func CallIdZeroValue

func CallIdZeroValue() CallId

func NewCallId

func NewCallId() CallId

func UnmarshalCallId

func UnmarshalCallId(b *protosupport.IdRaw) CallId

func (CallId) Equal

func (f CallId) Equal(other CallId) bool

func (CallId) High

func (f CallId) High() uint64

func (CallId) IsEmptyValue

func (f CallId) IsEmptyValue() bool

func (CallId) IsZeroOrEmptyValue

func (f CallId) IsZeroOrEmptyValue() bool

func (CallId) IsZeroValue

func (f CallId) IsZeroValue() bool

func (CallId) Low

func (f CallId) Low() uint64

func (CallId) Marshal

func (f CallId) Marshal() *protosupport.IdRaw

func (CallId) Short

func (f CallId) Short() string

func (CallId) String

func (f CallId) String() string

type DefCall

type DefCall struct{}

func (DefCall) Letter

func (f DefCall) Letter() byte

func (DefCall) ShortString

func (f DefCall) ShortString() string

type DefHost

type DefHost struct{}

func (DefHost) Letter

func (f DefHost) Letter() byte

func (DefHost) ShortString

func (f DefHost) ShortString() string

type DefMethod

type DefMethod struct{}

func (DefMethod) Letter

func (f DefMethod) Letter() byte

func (DefMethod) ShortString

func (f DefMethod) ShortString() string

type DefService

type DefService struct{}

func (DefService) Letter

func (f DefService) Letter() byte

func (DefService) ShortString

func (f DefService) ShortString() string

type HostId

type HostId IdRoot[DefHost]

func HostIdEmptyValue

func HostIdEmptyValue() HostId

func HostIdFromPair

func HostIdFromPair(high, low uint64) HostId

FromPair is probably not something you want to use unless you are pulling values from external storage or files. If you pulling values from the network, use the Marshal() ad Unmarshal() functions to work with Ids. Absolutely no checking is done on the values provided, so much caution is advised.

func HostIdZeroValue

func HostIdZeroValue() HostId

func NewHostId

func NewHostId() HostId

func UnmarshalHostId

func UnmarshalHostId(b *protosupport.IdRaw) HostId

func (HostId) Equal

func (f HostId) Equal(other HostId) bool

func (HostId) High

func (f HostId) High() uint64

func (HostId) IsEmptyValue

func (f HostId) IsEmptyValue() bool

func (HostId) IsZeroOrEmptyValue

func (f HostId) IsZeroOrEmptyValue() bool

func (HostId) IsZeroValue

func (f HostId) IsZeroValue() bool

func (HostId) Low

func (f HostId) Low() uint64

func (HostId) Marshal

func (f HostId) Marshal() *protosupport.IdRaw

func (HostId) Short

func (f HostId) Short() string

func (HostId) String

func (f HostId) String() string

type IdRoot

IdRoot[T] is used to indicate an id in parigot. This type is usually “covered up” by generated code that will given it a name lile FileId or QueueId so these types cannot be compared for equality, assigned to each other, and similar, despite being the same underlying type.

type IdRoot[T NameInfo] struct {
    // contains filtered or unexported fields
}

func NewIdRoot

func NewIdRoot[T NameInfo]() IdRoot[T]

NewIdRoot[T] returns a new Id of type[T] fille with 120 bits of randomness.

func NewIdTyped

func NewIdTyped[T NameInfo](h, l uint64) IdRoot[T]

NewIdType is dangerous in that it performs no checks about the validity of the data provided. Its use is discouraged. It will obey the values provided by the T type parameter regarding the high order byte, even if this value is provided in h.

func ZeroValue

func ZeroValue[T NameInfo]() IdRoot[T]

ZeroValue is a special value of an id. Thes should be returned when an Id should not be used, such as when an error is also returned from a function. Note that the zero value is not the same as the empty value.

func (IdRoot[T]) Equal

func (i IdRoot[T]) Equal(other IdRoot[T]) bool

Equal will compare two ids for equality. At this level it can compare _any_ two ids, but most users will be using generated code that disallows comparisons between id types. Note that the empty value and the zero value are not equal to anything, including each other.

func (IdRoot[T]) High

func (i IdRoot[T]) High() uint64

Use of High() is not recommended for user code. It returns the high 8 bytes of the 128bit id.

func (IdRoot[T]) IsEmptyValue

func (i IdRoot[T]) IsEmptyValue() bool

IsEmptyValue tells you if the given id is actually just full of zeros in the 15 data bytes. This almost means that the caller gave you a bad id, since the chance of all 15 data bytes being zero is very low, and vastly lower than somebody forgetting to initialize a value.

func (IdRoot[T]) IsZeroOrEmptyValue

func (i IdRoot[T]) IsZeroOrEmptyValue() bool

func (IdRoot[T]) IsZeroValue

func (i IdRoot[T]) IsZeroValue() bool

IsZeroValue checks an id value to see if it is the bit pattern of the zero value.

func (IdRoot[T]) Low

func (i IdRoot[T]) Low() uint64

Use of Low() is not recommended for user code. It returns the low 8 bytes of the 128bit id.

func (IdRoot[T]) Short

func (i IdRoot[T]) Short() string

Short returns a short string representing this value. Strings returned represent the low order 16 bits of the this Id. However, for debugging, this amount data is enough to uniquely identify a particular id. If you want to see the entire 120 bits, then use String().

func (IdRoot[T]) String

func (i IdRoot[T]) String() string

String() returns a string that contains the short string name of this id (like “file” or “queue”) and then 5 groups of numbers. From left to right these are bytes[4-6] of the high part, bytes[0-3] of the high part, bytes [4-7] of the low part, bytes[2-3] of the low part, and then low order two bytes of the low part. The low part is printed this way so the last section of the string match the portion of the id printed by Short()

func (IdRoot[V]) WriteGuestLe

func (i IdRoot[V]) WriteGuestLe(mem api.Memory, offset uint32) bool

WriteGuestLe will write an id into the guest memory when running on the host. This always writes the data in Little Endian format.

type MethodId

type MethodId IdRoot[DefMethod]

func MethodIdEmptyValue

func MethodIdEmptyValue() MethodId

func MethodIdFromPair

func MethodIdFromPair(high, low uint64) MethodId

FromPair is probably not something you want to use unless you are pulling values from external storage or files. If you pulling values from the network, use the Marshal() ad Unmarshal() functions to work with Ids. Absolutely no checking is done on the values provided, so much caution is advised.

func MethodIdZeroValue

func MethodIdZeroValue() MethodId

func NewMethodId

func NewMethodId() MethodId

func UnmarshalMethodId

func UnmarshalMethodId(b *protosupport.IdRaw) MethodId

func (MethodId) Equal

func (f MethodId) Equal(other MethodId) bool

func (MethodId) High

func (f MethodId) High() uint64

func (MethodId) IsEmptyValue

func (f MethodId) IsEmptyValue() bool

func (MethodId) IsZeroOrEmptyValue

func (f MethodId) IsZeroOrEmptyValue() bool

func (MethodId) IsZeroValue

func (f MethodId) IsZeroValue() bool

func (MethodId) Low

func (f MethodId) Low() uint64

func (MethodId) Marshal

func (f MethodId) Marshal() *protosupport.IdRaw

func (MethodId) Short

func (f MethodId) Short() string

func (MethodId) String

func (f MethodId) String() string

type NameInfo

type NameInfo interface {
    ShortString() string
    Letter() byte
}

type ServiceId

type ServiceId IdRoot[DefService]

func NewServiceId

func NewServiceId() ServiceId

func ServiceIdEmptyValue

func ServiceIdEmptyValue() ServiceId

func ServiceIdFromPair

func ServiceIdFromPair(high, low uint64) ServiceId

FromPair is probably not something you want to use unless you are pulling values from external storage or files. If you pulling values from the network, use the Marshal() ad Unmarshal() functions to work with Ids. Absolutely no checking is done on the values provided, so much caution is advised.

func ServiceIdZeroValue

func ServiceIdZeroValue() ServiceId

func UnmarshalServiceId

func UnmarshalServiceId(b *protosupport.IdRaw) ServiceId

func (ServiceId) Equal

func (f ServiceId) Equal(other ServiceId) bool

func (ServiceId) High

func (f ServiceId) High() uint64

func (ServiceId) IsEmptyValue

func (f ServiceId) IsEmptyValue() bool

func (ServiceId) IsZeroOrEmptyValue

func (f ServiceId) IsZeroOrEmptyValue() bool

func (ServiceId) IsZeroValue

func (f ServiceId) IsZeroValue() bool

func (ServiceId) Low

func (f ServiceId) Low() uint64

func (ServiceId) Marshal

func (f ServiceId) Marshal() *protosupport.IdRaw

func (ServiceId) Short

func (f ServiceId) Short() string

func (ServiceId) String

func (f ServiceId) String() string

Generated by gomarkdoc

Last modified July 4, 2023: going to merge this to check on codespaces (e9efa95)