Skip to content

Commit 9afb2d3

Browse files
author
Drew O'Meara
committed
doc edits
1 parent 0cc7650 commit 9afb2d3

File tree

1 file changed

+13
-9
lines changed

1 file changed

+13
-9
lines changed

py/run.go

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,18 @@ const (
1212
SingleMode CompileMode = "single" // Compile a single (interactive) statement
1313
)
1414

15-
// Context is gpython virtual environment instance ("context"), providing a mechanism
15+
// Context is a gpython environment instance container, providing a high-level mechanism
1616
// for multiple gpython interpreters to run concurrently without restriction.
1717
//
18-
// In general, one creates a py.Context (via py.NewContext) for each concurrent goroutine to be running an interpreter.
19-
// In other words, ensure that a py.Context is never concurrently accessed across goroutines.
18+
// Context instances maintain completely independent environments, namely the modules that
19+
// have been imported and their state. Modules imported into a Context are instanced
20+
// from a parent ModuleImpl. For example, since Contexts each have their
21+
// own sys module instance, each can set sys.path differently and independently.
2022
//
21-
// RunFile() and RunCode() block until code execution is complete.
22-
// In the future, they will abort early if the parent associated py.Context is signaled.
23+
// If you access a Context from multiple groutines, you are responsible that access is not concurrent,
24+
// with the exception of Close() and Done().
2325
//
24-
// See examples/multi-ctx
26+
// See examples/multi-context and examples/embedding.
2527
type Context interface {
2628

2729
// Resolves then compiles (if applicable) the given file system pathname into a py.Code ready to be executed.
@@ -31,6 +33,7 @@ type Context interface {
3133
ModuleInit(impl *ModuleImpl) (*Module, error)
3234

3335
// RunCode is a lower-level invocation to execute the given py.Code.
36+
// Blocks until execution is complete.
3437
RunCode(code *Code, globals, locals StringDict, closure Tuple) (result Object, err error)
3538

3639
// Returns the named module for this context (or an error if not found)
@@ -39,11 +42,12 @@ type Context interface {
3942
// Gereric access to this context's modules / state.
4043
Store() *ModuleStore
4144

42-
// Close signals that is context is about to go out of scope and any internal resources should be released.
43-
// Operations on a py.Context that have closed will generally result in an error.
44-
Close()
45+
// Close signals this context is about to go out of scope and any internal resources should be released.
46+
// Code execution on a py.Context that has been closed will result in an error.
47+
Close() error
4548

4649
// Done returns a signal that can be used to detect when this Context has fully closed / completed.
50+
// If Close() is called while execution in progress, Done() will not signal until execution is complete.
4751
Done() <-chan struct{}
4852
}
4953

0 commit comments

Comments
 (0)