Add SnapshotCreator API

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+- NewIsolate accepts option arguments. Thanks to [@GustavoCaso](https://github.com/GustavoCaso)
+- Add support for Snapshot creation. Thanks to [@GustavoCaso](https://github.com/GustavoCaso)
 
 ### Fixed
 - Use string length to ensure null character-containing strings in Go/JS are not terminated early.

context.go

@@ -76,6 +76,30 @@ func NewContext(opt ...ContextOption) *Context {
 	return ctx
 }
 
+// NewContextFromSnapshot creates a new JavaScript context from the Isolate startup data;
+// error will be of type `JSError` if not nil.
+func NewContextFromSnapshot(iso *Isolate, snapshot_index int) (*Context, error) {
+	ctxMutex.Lock()
+	ctxSeq++
+	ref := ctxSeq
+	ctxMutex.Unlock()
+
+	rtn := C.NewContextFromSnapshot(iso.ptr, C.size_t(snapshot_index), C.int(ref))
+
+	if rtn.context == nil {
+		return nil, newJSError(rtn.error)
+	}
+
+	ctx := &Context{
+		ref: ref,
+		ptr: rtn.context,
+		iso: iso,
+	}
+
+	ctx.register()
+	return ctx, nil
+}
+
 // Isolate gets the current context's parent isolate.An  error is returned
 // if the isolate has been terninated.
 func (c *Context) Isolate() *Isolate {

context_test.go

@@ -39,6 +39,61 @@ func TestContextExec(t *testing.T) {
 	}
 }
 
+func TestNewContextFromSnapshotErrorWhenIsolateHasNoStartupData(t *testing.T) {
+	t.Parallel()
+
+	iso := v8.NewIsolate()
+	defer iso.Dispose()
+
+	ctx, err := v8.NewContextFromSnapshot(iso, 1)
+
+	if ctx != nil {
+		t.Errorf("expected nil context got: %+v", ctx)
+	}
+	if err == nil {
+		t.Error("error expected but was <nil>")
+	}
+}
+
+func TestNewContextFromSnapshotErrorWhenIndexOutOfRange(t *testing.T) {
+	t.Parallel()
+
+	snapshotCreator := v8.NewSnapshotCreator()
+	snapshotCreatorIso, err := snapshotCreator.GetIsolate()
+	fatalIf(t, err)
+
+	snapshotCreatorCtx := v8.NewContext(snapshotCreatorIso)
+	defer snapshotCreatorCtx.Close()
+
+	snapshotCreatorCtx.RunScript(`const add = (a, b) => a + b`, "add.js")
+	snapshotCreatorCtx.RunScript(`function run() { return add(3, 4); }`, "main.js")
+	err = snapshotCreator.SetDefaultContext(snapshotCreatorCtx)
+	fatalIf(t, err)
+
+	snapshotCreatorCtx2 := v8.NewContext(snapshotCreatorIso)
+	defer snapshotCreatorCtx2.Close()
+
+	snapshotCreatorCtx2.RunScript(`const multiply = (a, b) => a * b`, "add.js")
+	snapshotCreatorCtx2.RunScript(`function run() { return multiply(3, 4); }`, "main.js")
+	index, err := snapshotCreator.AddContext(snapshotCreatorCtx2)
+	fatalIf(t, err)
+
+	data, err := snapshotCreator.Create(v8.FunctionCodeHandlingClear)
+	fatalIf(t, err)
+
+	iso := v8.NewIsolate(v8.WithStartupData(data))
+	defer iso.Dispose()
+
+	ctx, err := v8.NewContextFromSnapshot(iso, index+1)
+
+	if ctx != nil {
+		t.Errorf("expected nil context got: %+v", ctx)
+	}
+	if err == nil {
+		t.Error("error expected but was <nil>")
+	}
+}
+
 func TestJSExceptions(t *testing.T) {
 	t.Parallel()
 

isolate.go

@@ -25,8 +25,9 @@ type Isolate struct {
 	cbSeq   int
 	cbs     map[int]FunctionCallback
 
-	null      *Value
-	undefined *Value
+	null         *Value
+	undefined    *Value
+	createParams *CreateParams
 }
 
 // HeapStatistics represents V8 isolate heap statistics
@@ -44,20 +45,48 @@ type HeapStatistics struct {
 	NumberOfDetachedContexts uint64
 }
 
+type createOptions func(*CreateParams)
+
+func WithStartupData(startupData *StartupData) createOptions {
+	return func(params *CreateParams) {
+		params.startupData = startupData
+	}
+}
+
+type CreateParams struct {
+	startupData *StartupData
+}
+
 // NewIsolate creates a new V8 isolate. Only one thread may access
 // a given isolate at a time, but different threads may access
 // different isolates simultaneously.
 // When an isolate is no longer used its resources should be freed
 // by calling iso.Dispose().
+// If StartupData is passed as part of createOptions it will be use as part
+// of the createParams. The StartupData will be use when creating new context
+// from the Isolate.
 // An *Isolate can be used as a v8go.ContextOption to create a new
 // Context, rather than creating a new default Isolate.
-func NewIsolate() *Isolate {
+func NewIsolate(opts ...createOptions) *Isolate {
 	v8once.Do(func() {
 		C.Init()
 	})
+	params := &CreateParams{}
+	for _, opt := range opts {
+		opt(params)
+	}
+
+	var cOptions C.IsolateOptions
+
+	if params.startupData != nil {
+		cOptions.snapshot_blob_data = (*C.char)(unsafe.Pointer(&params.startupData.data[0]))
+		cOptions.snapshot_blob_raw_size = params.startupData.raw_size
+	}
+
 	iso := &Isolate{
-		ptr: C.NewIsolate(),
-		cbs: make(map[int]FunctionCallback),
+		ptr:          C.NewIsolate(cOptions),
+		cbs:          make(map[int]FunctionCallback),
+		createParams: params,
 	}
 	iso.null = newValueNull(iso)
 	iso.undefined = newValueUndefined(iso)
@@ -146,6 +175,7 @@ func (i *Isolate) Dispose() {
 		return
 	}
 	C.IsolateDispose(i.ptr)
+	i.createParams = nil
 	i.ptr = nil
 }
 

snapshot_creator.go

@@ -0,0 +1,118 @@
+// Copyright 2021 the v8go contributors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+package v8go
+
+// #include <stdlib.h>
+// #include "v8go.h"
+import "C"
+import (
+	"errors"
+	"unsafe"
+)
+
+type FunctionCodeHandling int
+
+//  Clear - does not keep any compiled data prior to serialization/deserialization/verify pass
+//  Keep - keeps any compiled data prior to serialization/deserialization/verify pass
+const (
+	FunctionCodeHandlingClear FunctionCodeHandling = iota
+	FunctionCodeHandlingKeep
+)
+
+// StartupData stores the snapshot blob data
+type StartupData struct {
+	data     []byte
+	raw_size C.int
+}
+
+// SnapshotCreator allows creating snapshot.
+type SnapshotCreator struct {
+	ptr                 C.SnapshotCreatorPtr
+	iso                 *Isolate
+	defaultContextAdded bool
+}
+
+// NewSnapshotCreator creates a new snapshot creator.
+func NewSnapshotCreator() *SnapshotCreator {
+	v8once.Do(func() {
+		C.Init()
+	})
+
+	rtn := C.NewSnapshotCreator()
+
+	return &SnapshotCreator{
+		ptr:                 rtn.creator,
+		iso:                 &Isolate{ptr: rtn.iso},
+		defaultContextAdded: false,
+	}
+}
+
+// GetIsolate returns the Isolate associated with the SnapshotCreator.
+// This Isolate must be used to create the contexts that later will be used to create the snapshot blob.
+func (s *SnapshotCreator) GetIsolate() (*Isolate, error) {
+	if s.ptr == nil {
+		return nil, errors.New("v8go: Cannot get Isolate after creating the blob")
+	}
+
+	return s.iso, nil
+}
+
+// SetDefaultContext set the default context to be included in the snapshot blob.
+func (s *SnapshotCreator) SetDefaultContext(ctx *Context) error {
+	if s.defaultContextAdded {
+		return errors.New("v8go: Cannot set multiple default context for snapshot creator")
+	}
+
+	C.SetDefaultContext(s.ptr, ctx.ptr)
+	s.defaultContextAdded = true
+	ctx.ptr = nil
+
+	return nil
+}
+
+// AddContext add additional context to be included in the snapshot blob.
+// Returns the index of the context in the snapshot blob, that later can be use to call v8go.NewContextFromSnapshot.
+func (s *SnapshotCreator) AddContext(ctx *Context) (int, error) {
+	if s.ptr == nil {
+		return 0, errors.New("v8go: Cannot add context to snapshot creator after creating the blob")
+	}
+
+	index := C.AddContext(s.ptr, ctx.ptr)
+	ctx.ptr = nil
+
+	return int(index), nil
+}
+
+// Create creates a snapshot data blob.
+// The snapshot creator instance is unsable after creating the snapshot data blob.
+func (s *SnapshotCreator) Create(functionCode FunctionCodeHandling) (*StartupData, error) {
+	if s.ptr == nil {
+		return nil, errors.New("v8go: Cannot use snapshot creator after creating the blob")
+	}
+
+	if !s.defaultContextAdded {
+		return nil, errors.New("v8go: Cannot create a snapshot without a default context")
+	}
+
+	rtn := C.CreateBlob(s.ptr, C.int(functionCode))
+
+	s.ptr = nil
+	s.iso.ptr = nil
+
+	raw_size := rtn.raw_size
+	data := C.GoBytes(unsafe.Pointer(rtn.data), raw_size)
+
+	C.SnapshotBlobDelete(rtn)
+
+	return &StartupData{data: data, raw_size: raw_size}, nil
+}
+
+// Dispose deletes the reference to the SnapshotCreator.
+func (s *SnapshotCreator) Dispose() {
+	if s.ptr != nil {
+		C.DeleteSnapshotCreator(s.ptr)
+		s.ptr = nil
+	}
+}