Guest APIs

Guest APIs are the guest side APIs (your program) of the built-in services and parigot proper. APIs listed as syscall are the calls to the pubilc API of parigot.

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(ctx context.Context, 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 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 CompleteCall

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

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

func CurrentHostId

func CurrentHostId() id.HostId

CurrentHostId provides the interface to the runner’s chosen host id for our WASM machine. That value is communicated through environment variables.

func CurrentTimezone

func CurrentTimezone() *time.Location

CurrentTimezone provides the interface to the configuration file’s timezone string for our WASM machine. That value is communicated through environment variables.

func Dispatch

func Dispatch(ctx context.Context, 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_(int32, int32, int32, int32) int64

Exit is called from the WASM side to cause the WASM program, or all the WASM programs, to exit. It does not return.

func ExpireMethod

func ExpireMethod(ctx context.Context, curr time.Time)

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 Export

func Export(ctx context.Context, 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_(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(ctx context.Context, 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 MatchCompleter

func MatchCompleter(ctx context.Context, t time.Time, hid id.HostId, origHost id.HostId, 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. The time value has be passed in from the outside.

func MustBindMethodName

func MustBindMethodName(ctx context.Context, in *syscall.BindMethodRequest) id.MethodId

func NewExitCompleter

func NewExitCompleter(f *ExitFuture) future.Completer

func NewLaunchCompleter

func NewLaunchCompleter(f *LaunchFuture) future.Completer

func ReadOne

func ReadOne(ctx context.Context, 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(ctx context.Context, 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(ctx context.Context, 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(ctx context.Context, 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.

type ExitCompleter

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

func (*ExitCompleter) Cancel

func (l *ExitCompleter) Cancel()

func (*ExitCompleter) CompleteMethod

func (l *ExitCompleter) CompleteMethod(ctx context.Context, a proto.Message, e int32, orig id.HostId) syscall.KernelErr

func (*ExitCompleter) Completed

func (l *ExitCompleter) Completed() bool

func (*ExitCompleter) Failure

func (l *ExitCompleter) Failure(failFunc func(int32))

func (*ExitCompleter) Success

func (l *ExitCompleter) Success(succFunc func(proto.Message))

type ExitFuture

ExitFuture is the return type of Exit() on the guest side. This is a future because it is not certain exactly when the Exit will actually occur. Further, the exit itself might fail, so the program may not exit at all.

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

func Exit

func Exit(ctx context.Context, inPtr *syscall.ExitRequest) *ExitFuture

func NewExitFuture

func NewExitFuture() *ExitFuture

NewExitFuture returns an initialized exit future. It is not useful to attempt to determine if the exit has “completed” as the program would no longer exit.

func (*ExitFuture) Cancel

func (l *ExitFuture) Cancel()

func (*ExitFuture) CompleteMethod

func (l *ExitFuture) CompleteMethod(ctx context.Context, lr *syscall.ExitResponse, err syscall.KernelErr)

CompleteMethod is used to complete a previously defined future of type ExitFuture.

func (*ExitFuture) Completed

func (l *ExitFuture) Completed() bool

func (*ExitFuture) Failure

func (l *ExitFuture) Failure(fn func(syscall.KernelErr))

Failure should be called to add a function to be called when the Exit() has fully completed and was unsuccessful. Note that this situation is a serious internal error in parigot when the given method fn is called. It is appropriate to take drastic measures like `os.Exit(1)` to force the abort of the program.

func (*ExitFuture) Success

func (l *ExitFuture) Success(fn func(*syscall.ExitResponse))

Success should be called to add a function to be called when the Exit() has fully completed and did so successfully. Adding an exit function here can useful to clean up resources, with the understanding that the program is _about_ to exit. The function fn should NOT exit the program with a call like os.Exit(1), this will happen once all the Success functions on the ExitFuture have been called.

type LaunchCompleter

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

func (*LaunchCompleter) Cancel

func (l *LaunchCompleter) Cancel()

func (*LaunchCompleter) CompleteMethod

func (l *LaunchCompleter) CompleteMethod(ctx context.Context, a proto.Message, e int32, orig id.HostId) syscall.KernelErr

func (*LaunchCompleter) Completed

func (l *LaunchCompleter) Completed() bool

func (*LaunchCompleter) Failure

func (l *LaunchCompleter) Failure(failFunc func(int32))

func (*LaunchCompleter) Success

func (l *LaunchCompleter) Success(succFunc func(proto.Message))

type LaunchFuture

LaunchFuture is the return type of Launch() on the guest side. The guest receives the future in response to a Launch() call and should attach Success() and Failure() funcs as needed. If the Completed() call is true, the methods added in Success() or Failure() will be called immediately.

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

func Launch

func Launch(ctx context.Context, inPtr *syscall.LaunchRequest) *LaunchFuture

func NewLaunchFuture

func NewLaunchFuture() *LaunchFuture

func (*LaunchFuture) Cancel

func (l *LaunchFuture) Cancel()

func (*LaunchFuture) CompleteMethod

func (l *LaunchFuture) CompleteMethod(ctx context.Context, lr *syscall.LaunchResponse, err syscall.KernelErr)

CompleteMethod fills in the results for a Method future and it works the same for LaunchResponse.

func (*LaunchFuture) Completed

func (l *LaunchFuture) Completed() bool

Completed returns if the given LaunchFuture has already been completed. This might be interesting for some guests if they wish to bypass the futures mechanism in the case where the Launch() has already finished. Note that quick completion of Launch() is NOT guaranteed in all cases so clients that use this method to bypass futures must also have a backup approach for when the Launch() takes some time to complete.

func (*LaunchFuture) Failure

func (l *LaunchFuture) Failure(fn func(syscall.KernelErr))

Failure should be called to add a function to be called when the Launch() has fully completed and was unsuccessful.

func (*LaunchFuture) Success

func (l *LaunchFuture) Success(fn func(*syscall.LaunchResponse))

Success should be called to add a function to be called when the Launch() has fully completed and did so successfully.

lib

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

Index

func CurrentTime

func CurrentTime(ctx context.Context) (context.Context, time.Time)

CurrentTime returns the current time in the current timezone unless the current time has been set with SetCurrentTime. If that is the case, it returns the values provided to SetCurrentTime, in order. Note that the returned context.Context should be used as a replacement for the context provided as a parameter, because the state of the context changed.

All guest code should use this call rather than time.Now() or similar to provide a convenient way to test time-dependent behavior.

func ExitAll

func ExitAll(ctx context.Context, code int32, myId id.ServiceId) *syscallguest.ExitFuture

ExitAll sends a request to exit on all hosts and when the future is completed, it will exit. Valid code values must be in the range 0 to 192, inclusive.

func ExitSelf

func ExitSelf(ctx context.Context, code int32, myId id.ServiceId) *syscallguest.ExitFuture

ExitSelf sends a request to exit and when the future is completed it will exit. Valid code values must be in the range 0 to 192, inclusive. If ExitSelf() is called by the last running guest program then the entire process will exit.

func Export1

func Export1(ctx context.Context, pkg, name string, serviceId id.ServiceId) (*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 LaunchClient

func LaunchClient(ctx context.Context, myId id.ServiceId) *syscallguest.LaunchFuture

LaunchClient is a convienence wrapper around Launch() for clients that don’t want to create their own request structure.

func MustInitClient

func MustInitClient(requirement []MustRequireFunc) (context.Context, 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() (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 ReadOneAndCallClient

func ReadOneAndCallClient(ctx context.Context, binding *ServiceMethodMap, timeoutInMillis int32) syscall.KernelErr

ReadOneAndCallClient does the waiting for an incoming call and if one arrives, it dispatches the call to the appropriate method. Similarly, it will detect and respond to finished futures. It returns KernelErr_ReadOneTimeout if the waiting timed out, otherwise the value should be KernelErr_NoError or an appropriate error code.

func Require1

func Require1(ctx context.Context, 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.

func SetCurrentTime

func SetCurrentTime(ctx context.Context, t ...time.Time) context.Context

SetCurrentTime should only be used in tests. Calling this method _freezes_ time so that future calls will see a chosen time (in t) as the current time. Every call to CurrentTime() receives the next value in the sequence provided by t. If there are more calls than values in t, the sequence is restarted from the beginning, thus providing a single value “stops time” at that point.

The returned context.Context should be used as a replacement for the context provided as a parameter.

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 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 ReadyChecker

type ReadyChecker interface {
    Ready(ctx context.Context, sid id.ServiceId) *future.Base[bool]
}

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 Invoker 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(ctx context.Context, method id.MethodId, param proto.Message) (id.HostId, 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, orig id.HostId) syscall.KernelErr
    Success(func(proto.Message))
    Failure(func(int32))
    Completed() bool
    Cancel()
}

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. In principle, this could vary by go compiler, but most use this C-originated convention.

const EntryPointSymbol = "_start"

ExitCode is the name of a wasm symbol that holds the exit code of a process.

const ExitCode = "exit_code_"

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 FileServiceMaxPathPart = 20


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

this is the value used for a panic that is intended to be a controlled exit

var ControlledExit = "controlled exit via panic:"

this is really a “phantom” serivce, used only for exiting

var ExitMethod = id.MethodId(id.NewIdTyped[id.DefMethod](^uint64(0), 0xfffffffffffffff2))

this is really a “phantom” serivce, used only for exiting

var ExitService = id.ServiceId(id.NewIdTyped[id.DefService](^uint64(0), 0xfffffffffffffff1))

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)

all calls to launch use the same Id

var LaunchMethod = id.MethodId(id.NewIdTyped[id.DefMethod](^uint64(0), 0xfffffffffffffff0))

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 September 8, 2023: updated docs, added protoc-gen-doc to dockerfile (10e27b1)