progpAPI

package module
v2.0.6 Latest Latest
Warning

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

 Go to latest Published: Feb 19, 2024 License: Apache-2.0 Imports: 14 Imported by: 5

README

ProgpJS ProgpAPI

It's the low level API for the javascript engine. It's mainly used when you want to add special features to a Go function exposed to the javascript engine, like progpAPI.StringBuffer which allows to return a buffer when a string is expected (it's allow avoiding buffer to string conversion).

The split between ProgpAPI and progpScripts has this logic: ProgpJS modules must only access progpAPI and never progpScripts. Mainly because an update to ProgpAPI involves regenerating all the pre-compiled Go plugins, theses being very usefully since libProgpV8 take about 5 secondes to compiles without that.

See https://github.com/progpjs/documentation for more information.

Documentation

Index

Constants

View Source 
const MaxResourceIdSize = 2147483647

Variables

This section is empty.

Functions

func CatchFatalErrors 

func CatchFatalErrors()

func ConfigRegisterScriptEngineBuilder 

func ConfigRegisterScriptEngineBuilder(engineName string, builder ScriptEngineBuilder)

func DeclareBackgroundTaskEnded 

func DeclareBackgroundTaskEnded()

func DeclareBackgroundTaskStarted 

func DeclareBackgroundTaskStarted()

func DynamicCallFunction 

func DynamicCallFunction(toCall any, callArgs []reflect.Value) (result []reflect.Value, errorMsg string)

func ForEachScriptEngine 

func ForEachScriptEngine(f func(engine ScriptEngine))

func ForceExitingVM 

func ForceExitingVM()

ForceExitingVM allows stopping the process without doing an os.exit. It's a requirement if profiling the memory, since without that, the log file isn't correctly flushed.

func GoStringToQuotedString2 

func GoStringToQuotedString2(value string) string

func OnUnCatchScriptError 

func OnUnCatchScriptError(error *JsErrorMessage)

func PauseMs 

func PauseMs(timeInMs int)

func ReflectValueToAny 

func ReflectValueToAny(resV reflect.Value) any

func SafeGoRoutine 

func SafeGoRoutine(f func())

func SetErrorTranslator 

func SetErrorTranslator(handler ErrorTranslatorF)

func SetScriptFileCompiler 

func SetScriptFileCompiler(compiler ScriptFileCompilerF)

func SetScriptFileExecutor 

func SetScriptFileExecutor(executor ScriptFileExecutorF)

func WaitTasksEnd 

func WaitTasksEnd()

WaitTasksEnd wait until all background tasks are finished. It's used in order to know if the application can exit.

Types

type CheckAllowedFunctionsF 

type CheckAllowedFunctionsF func(securityGroup string, functionGroup string, functionName string) bool

type DisposeSharedResourceF 

type DisposeSharedResourceF func(value any)

type EmbeddedFile 

type EmbeddedFile struct {
	FS        embed.FS
	InnerPath string
}

func (*EmbeddedFile) Read 

func (m *EmbeddedFile) Read() ([]byte, error)

type ErrorTranslatorF 

type ErrorTranslatorF func(error *JsErrorMessage)

type FunctionGroup 

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

func (*FunctionGroup) AddAsyncFunction 

func (m *FunctionGroup) AddAsyncFunction(jsName string, goFunctionName string, jsFunction any)

func (*FunctionGroup) AddFunction 

func (m *FunctionGroup) AddFunction(javascriptName string, goFunctionName string, goFunctionRef any)

type FunctionModule 

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

func (*FunctionModule) AddAsyncFunction 

func (m *FunctionModule) AddAsyncFunction(jsName string, goFunctionName string, jsFunction any)

AddAsyncFunction add an async function to a javascript group which name is the name of the go namespace last part.

func (*FunctionModule) AddFunction 

func (m *FunctionModule) AddFunction(javascriptName string, goFunctionName string, goFunctionRef any)

AddFunction add a function to a javascript group which name is the name of the go namespace last part.

func (*FunctionModule) DeclareNodeModule 

func (m *FunctionModule) DeclareNodeModule(embedded embed.FS, embeddedDirPath string, modName string)

func (*FunctionModule) GetFunctionRegistry 

func (m *FunctionModule) GetFunctionRegistry() *FunctionRegistry

func (*FunctionModule) ModName 

func (m *FunctionModule) ModName() string

func (*FunctionModule) UseCustomGroup 

func (m *FunctionModule) UseCustomGroup(jsGroupName string) *FunctionGroup

UseCustomGroup allows using another javascript group than the default group for this go namespace.

func (*FunctionModule) UseGroupGlobal 

func (m *FunctionModule) UseGroupGlobal() *FunctionGroup

UseGroupGlobal allows using the global group where functionsArray directly accessible to javascript scripts without importing them.

type FunctionRegistry 

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

func GetFunctionRegistry 

func GetFunctionRegistry() *FunctionRegistry

func (*FunctionRegistry) EnableDynamicMode 

func (m *FunctionRegistry) EnableDynamicMode(enabled bool)

func (*FunctionRegistry) GetAllFunctions 

func (m *FunctionRegistry) GetAllFunctions(sortList bool) []*RegisteredFunction

func (*FunctionRegistry) GetEmbeddedModulesTSX 

func (m *FunctionRegistry) GetEmbeddedModulesTSX() map[string]EmbeddedFile

func (*FunctionRegistry) GetNamespaces 

func (m *FunctionRegistry) GetNamespaces() map[string]bool

func (*FunctionRegistry) GetRefToFunction 

func (m *FunctionRegistry) GetRefToFunction(jsFunctionName string) *RegisteredFunction

func (*FunctionRegistry) IsUsingDynamicMode 

func (m *FunctionRegistry) IsUsingDynamicMode() bool

func (*FunctionRegistry) UseGoNamespace 

func (m *FunctionRegistry) UseGoNamespace(goNamespace string) *FunctionModule

type JsContext 

type JsContext interface {
	GetScriptEngine() ScriptEngine

	// GetSecurityGroup returns a group name which allows knowing the category of this context.
	// It's mainly used to allows / don't allow access to some functions groups.
	// For exemple you can use security group "unsafe" then the script will no be able to access to Go functions.
	//
	GetSecurityGroup() string

	// ExecuteScript executes a script inside this context.
	// It must be used once and don't allow executing more than one script.
	ExecuteScript(scriptContent string, compiledFilePath string, sourceScriptPath string) *JsErrorMessage

	// ExecuteScriptFile is like ExecuteScript but allows using a file (which can be typescript).
	ExecuteScriptFile(scriptPath string) *JsErrorMessage

	// ExecuteChildScriptFile execute a script from the inside of another script.
	ExecuteChildScriptFile(scriptPath string) error

	// TryDispose destroy the context and free his resources.
	// It's do nothing if this context can't be disposed, for
	// exemple if the engine only support one context.
	//
	TryDispose() bool

	// DisarmError remove the current error and allows continuing execution.
	// The error params allows to avoid case where a new error occurs since.
	DisarmError(error *JsErrorMessage)

	// IncreaseRefCount increase the ref counter for the context.
	// This avoids that the script exit, which is required the system is
	// keeping reference on some javascript functions.
	IncreaseRefCount()

	// DecreaseRefCount decrease the ref counter for the context.
	DecreaseRefCount()
}

type JsErrorMessage 

type JsErrorMessage struct {
	Error      string
	ErrorLevel int

	StartColumn int
	EndColumn   int

	StartPosition int
	EndPosition   int

	SourceMapUrl string
	ScriptPath   string

	StackTraceFrameCount int
	StackTraceFrames     []StackTraceFrame
	// contains filtered or unexported fields
}

func NewScriptErrorMessage 

func NewScriptErrorMessage(ctx JsContext) *JsErrorMessage

func (*JsErrorMessage) DisarmError 

func (m *JsErrorMessage) DisarmError(ctx JsContext)

DisarmError allows to continue after an un-catch error.

func (*JsErrorMessage) GetScriptContext 

func (m *JsErrorMessage) GetScriptContext() JsContext

func (*JsErrorMessage) LogError 

func (m *JsErrorMessage) LogError()

func (*JsErrorMessage) Print 

func (m *JsErrorMessage) Print(forcePrinting bool)

func (*JsErrorMessage) StackTrace 

func (m *JsErrorMessage) StackTrace() string

func (*JsErrorMessage) Translate 

func (m *JsErrorMessage) Translate()

type JsFunction 

type JsFunction interface {
	CallWithUndefined()

	CallWithError(err error)

	// KeepAlive allows to avoid destroying the function after the first call.
	// It must be used when you keep a reference to a function.
	//
	KeepAlive()

	// EnabledResourcesAutoDisposing allows the engine to automatically dispose the resources created while
	// calling this function. Without that you must call progpDispose on each disposable resources.
	// Here no, when activating this flag the engine release all the resource one the function call ends.
	// This includes all the async functions launched from this function and not only the main body of the function.
	//
	// If you are interested in this functionality, you can use the javascript function progpAutoDispose(() => { ... })
	//
	EnabledResourcesAutoDisposing(currentResourceContainer *SharedResourceContainer)

	CallWithArrayBuffer2(buffer []byte)
	CallWithString2(value string)
	CallWithStringBuffer2(value []byte)

	CallWithDouble1(value float64)
	CallWithDouble2(value float64)

	CallWithBool2(value bool)

	CallWithResource1(value *SharedResource)
	CallWithResource2(value *SharedResource)
}

type ParsedGoFunction 

type ParsedGoFunction struct {
	GeneratorUniqName string
	GoFunctionName    string

	ParamTypes          []string
	ParamTypeRefs       []reflect.Type
	CallParamNamespaces []string

	ReturnType        string
	ReturnErrorOffset int

	JsFunctionName string
	JsGroupName    string
}

func ParseGoFunction 

func ParseGoFunction(fct *RegisteredFunction) (ParsedGoFunction, error)

func (*ParsedGoFunction) GetGoFunctionName 

func (m *ParsedGoFunction) GetGoFunctionName() string

func (*ParsedGoFunction) GetJsFunctionName 

func (m *ParsedGoFunction) GetJsFunctionName() string

type RegisteredFunction 

type RegisteredFunction struct {
	IsAsync            bool
	Group              string
	JsFunctionName     string
	GoFunctionName     string
	GoFunctionFullName string
	GoFunctionRef      any
	GoFunctionInfos    ParsedGoFunction
}

type RuntimeErrorHandlerF 

type RuntimeErrorHandlerF func(ctx JsContext, err *JsErrorMessage) bool

type ScriptCallbackF 

type ScriptCallbackF func(error *JsErrorMessage)

type ScriptEngine 

type ScriptEngine interface {
	// Start the engine, which is call one all is initialized in the Go side.
	Start()

	// GetEngineLanguage allows to know if it' a "javascript" engine or a "python" engine.
	GetEngineLanguage() string

	// GetEngineName the name of the underlying engine. For exemple "progpv8".
	GetEngineName() string

	WaitDebuggerReady()

	// GetInternalEngineVersion the version of the engine used internally.
	// For exemple if it's using Google V8, then return the v8 engine version.
	GetInternalEngineVersion() string

	// Shutdown stop the engine. He can't be used anymore after that.
	// It mainly occurs after a fatal error or at script ends.
	Shutdown()

	// CreateNewScriptContext creates a new context which can be used
	// to execute a new script context from the others scripts.
	//
	CreateNewScriptContext(securityGroup string, mustDebug bool) JsContext

	// SetRuntimeErrorHandler allows to set a function which will manage runtime error.
	// The handler runtime true if the error is handler or false
	// to use the default behavior, which consist of printing the error and exit.
	//
	SetRuntimeErrorHandler(handler RuntimeErrorHandlerF)

	// SetScriptTerminatedHandler allows to add a function triggered when the script has finished his execution, with or without error.
	// It's call when all asynchronous function are executed, end before the end of the background tasks.
	// (mainly because this tasks can continue to executed without needing the javascript VM anymore)
	//
	SetScriptTerminatedHandler(handler ScriptTerminatedHandlerF)

	SetAllowedFunctionsChecker(handler CheckAllowedFunctionsF)
}

func GetScriptEngine 

func GetScriptEngine(engineName string) ScriptEngine

type ScriptEngineBuilder 

type ScriptEngineBuilder = func() ScriptEngine

type ScriptExecResult 

type ScriptExecResult struct {
	ScriptError *JsErrorMessage
	GoError     error
}

func (*ScriptExecResult) HasError 

func (m *ScriptExecResult) HasError() bool

func (*ScriptExecResult) PrintError 

func (m *ScriptExecResult) PrintError() bool

type ScriptFileCompilerF 

type ScriptFileCompilerF func(scriptPath string) (string, string, error)

func GetScriptFileCompiler 

func GetScriptFileCompiler() ScriptFileCompilerF

type ScriptFileExecutorF 

type ScriptFileExecutorF func(ctx JsContext, scriptPath string) *JsErrorMessage

func GetScriptFileExecutor 

func GetScriptFileExecutor() ScriptFileExecutorF

type ScriptTerminatedHandlerF 

type ScriptTerminatedHandlerF func(ctx JsContext, scriptPath string, err *JsErrorMessage) *JsErrorMessage

type SharedResource 

type SharedResource struct {
	Value any
	// contains filtered or unexported fields
}

func (*SharedResource) Dispose 

func (m *SharedResource) Dispose()

func (*SharedResource) GetId 

func (m *SharedResource) GetId() int

type SharedResourceContainer 

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

func NewSharedResourceContainer 

func NewSharedResourceContainer(parent *SharedResourceContainer, ctx JsContext) *SharedResourceContainer

func (*SharedResourceContainer) Dispose 

func (m *SharedResourceContainer) Dispose()

func (*SharedResourceContainer) GetResource 

func (m *SharedResourceContainer) GetResource(resId int) *SharedResource

func (*SharedResourceContainer) GetScriptContext 

func (m *SharedResourceContainer) GetScriptContext() JsContext

func (*SharedResourceContainer) NewSharedResource 

func (m *SharedResourceContainer) NewSharedResource(value any, onDispose DisposeSharedResourceF) *SharedResource

type StackTraceFrame 

type StackTraceFrame struct {
	Line     int
	Column   int
	Function string
	Source   string
}

type StringBuffer 

type StringBuffer []byte

StringBuffer allows the code generator to known that we want this bytes to be send as if it was a string. Allows to avoid the cost of converting []byte to string before calling javascript.

type TaskQueue 

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

TaskQueue allows executing the C++ calls from only one thread. Without that, Go can be short on available threads which lead to a crash.

This protection is only required where there is a lot of calls that can be blocked the thread. It's essentially when calling an event and calling a callback function.

func NewTaskQueue 

func NewTaskQueue() *TaskQueue

func (*TaskQueue) Exit 

func (m *TaskQueue) Exit(onExited func())

func (*TaskQueue) IsDisposed 

func (m *TaskQueue) IsDisposed() bool

func (*TaskQueue) Push 

func (m *TaskQueue) Push(f func())

type V8ScriptCallback 

type V8ScriptCallback func(result ScriptExecResult)

Source Files

View all Source files

Directories

Path Synopsis

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.