Working with Contexts

## Working with Contexts Working with Contexts — Self-contained JavaScript execution environments |

## Synopsis

    #include <seed/seed.h>

    typedef             SeedContext;
    typedef             SeedGlobalContext;
    typedef             SeedContextGroup;
    SeedGlobalContext   seed_context_create                 (SeedContextGroup group,
                                                             SeedClass global_class);
    SeedGlobalContext   seed_context_ref                    (SeedGlobalContext ctx);
    void                seed_context_unref                  (SeedGlobalContext ctx);
    void                seed_context_collect                (SeedGlobalContext ctx);
    SeedObject          seed_context_get_global_object      (SeedContext ctx);
    void                seed_prepare_global_context         (SeedContext ctx);
    void                seed_importer_add_global            (SeedContext ctx,
                                                             gchar *name);
    void                seed_importer_set_search_path       (SeedContext ctx,
                                                             gchar **search_path);

## Description

A SeedContext provides a complete "universe" for the execution of JavaScript. You can use `seed_context_create()` to create a sandboxed context that lacks the import system, so it can be used to execute somewhat untrusted JavaScript (as it has no way to access the rest of your system). You can also expose the default set of globals (including "print", "imports", and "Seed") to create more powerful but still self-contained environments within which to execute code.

Example 6. Using a Seed context as a form of sandboxing

    ...
    ctx = seed_context_create(NULL, NULL);
    script = seed_make_script(ctx, "print(imports)", NULL, 0);
    // nothing is printed, because imports is undefined, because we're in a sandbox
    ...

The sandbox module provides access to this system from the JavaScript side of Seed.

## Details

### SeedContext

    typedef gpointer SeedContext;

### SeedGlobalContext

    typedef gpointer SeedGlobalContext;

### SeedContextGroup

    typedef gpointer SeedContextGroup;

### seed_context_create ()

    SeedGlobalContext   seed_context_create                 (SeedContextGroup group,
                                                             SeedClass global_class);

Create a new SeedContext. By default, this creates a new context which has no global objects; you can add the default set using `seed_prepare_global_context()`.

`group` : | A SeedContextGroup in which to create the new context, or `NULL` to create it in the default context group.
`global_class` : | The SeedClass to use to create the global object, or `NULL` to create it with the default class.
Returns : | A new SeedContext.

### seed_context_ref ()

    SeedGlobalContext   seed_context_ref                    (SeedGlobalContext ctx);

Increments the reference count of `ctx`.

`ctx` : | A SeedContext.
Returns : | `ctx`

### seed_context_unref ()

    void                seed_context_unref                  (SeedGlobalContext ctx);

Decrements the reference count of `ctx`.

`ctx` : | A SeedContext.

### seed_context_collect ()

    void                seed_context_collect                (SeedGlobalContext ctx);

Instructs JavaScriptCore to make a garbage collection pass. The context parameter is currently unused, and a pass is made through all contexts.

`ctx` : | A SeedContext.

### seed_context_get_global_object ()

    SeedObject          seed_context_get_global_object      (SeedContext ctx);

`ctx` : | A valid SeedContext
Returns : | The global object for `ctx`.

### seed_prepare_global_context ()

    void                seed_prepare_global_context         (SeedContext ctx);

Adds the default set of global objects (imports, GType, Seed, and print) to a fresh SeedContext.

`ctx` : | A SeedContext on which to add the default set of global objects.

### seed_importer_add_global ()

    void                seed_importer_add_global            (SeedContext ctx,
                                                             gchar *name);

### seed_importer_set_search_path ()

    void                seed_importer_set_search_path       (SeedContext ctx,
                                                             gchar **search_path);