wren/doc/site/embedding/calling-wren-from-c.markdown

^title Calling Wren from C

From C, we can tell Wren to do stuff by calling `wrenInterpret()`, but that's
not always the ideal way to drive the VM. First of all, it's slow. It has to
parse and compile the string of source code you give it. Wren has a pretty fast
compiler, but that's still a good bit of work.

It's also not an effective way to communicate. You can't pass arguments to
Wren—at least, not without doing something nasty like converting them to
literals in a string of source code—and we can't get a result value back.

`wrenInterpret()` is great for loading code into the VM, but it's not the best
way to execute code that's already been loaded. What we want to do is invoke
some already compiled chunk of code. Since Wren is an object-oriented language,
"chunk of code" means a [method][], not a [function][].

[method]: ../method-calls.html
[function]: ../functions.html

The C API for doing this is `wrenCall()`. In order to invoke a Wren method from
C, first we need a few things:

* **The method to call.** Wren is dynamically typed, so this means we'll look it
  up by name. Further, since Wren supports overloading by arity, we actually
  need its entire [signature][].

[signature]: ../method-calls.html#signature

* **The receiver to invoke the method on.** It's the receiver's class that
  determines which method is actually called.

* **The arguments to pass to the method.**

We'll tackle these one at a time.

### Getting a method handle

When you run a chunk of Wren code like this:

    :::wren
    object.someMethod(1, 2, 3)

At runtime, the VM has to look up the class of `object` and find a method there
whose signature is `someMethod(_,_,_)`. This sounds like it's doing some string
manipulation—at the very least hashing the signature—every time a
method is called. That's how many dynamic languages work.

But, as you can imagine, that's pretty slow. So, instead, Wren does as much of
that work at compile time as it can. When it's compiling the above code to
bytecode, it takes that method signature a converts it to a *method symbol*, a
number that uniquely identifes that method. That's the only part of the process
that requires treating a signature as a string.

At runtime, the VM just looks for the method *symbol* in the receiver's class's
method table. In fact, the way it's implemented today, the symbol is simply the
array index into the table. That's why method calls are so fast in Wren.

It would be a shame if calling a method from C didn't have that same speed
benefit. So to do that, we split the process of calling a method into two steps.

First, we create a handle that represents a "compiled" method signature. You do
that using this:

    :::c
    WrenHandle* wrenMakeCallHandle(WrenVM* vm, const char* signature);

That takes a method signature as a string and gives you back an opaque handle
that represents the compiled method symbol. Now you have a *reusable* handle
that can be used to very quickly call a certain method given a receiver and some
arguments.

This is just a regular WrenHandle, which means you can hold onto it as long as
you like. Typically, you'd call this once outside of your applications
performance critical loops and reuse it as long as you need. Then, it is us up
to you to release it when you no longer need it by calling
`wrenReleaseHandle()`.

### Setting up a receiver

OK, we have a method, but who are we calling it on? We need a receiver, and as
you can probably guess after reading the [last section][], we give that to Wren
by storing it in a slot. In particular, **the receiver for a method call goes in
slot zero.**

Any object you store in that slot can be used as a receiver. You could even call
`+` on a number by storing a number in there if you felt like it.

[last section]: slots-and-handles.html

*Needing* to pick some kind of receiver from C might feel strange. C is
procedural, so it's natural to want to just invoke a bare *function* from Wren,
but Wren isn't procedural. Instead, if you want to define some executable
operation that isn't logically tied to a specific object, the natural way is to
define a static method on an appropriate class.

For example, say we're making a game engine. From C, we want to tell the game
engine to update all of the entities each frame. We'll keep track of the list of
entities within Wren, so from C, there's no obvious object to call `update(_)`
on. Instead, we'll just make it a static method:

    :::wren
    class GameEngine {
      static update(elapsedTime) {
        // ...
      }
    }

So, very often, when you call a method from C, you'll be calling a static
method. But, even then, you need a receiver. Now, though, the receiver is the
*class itself*. Classes are first class objects in Wren, and when you define a
named class, you're really declaring a variable with the class's name and
storing a reference to the class object in it.

Assuming you declared that class at the top level, the C API [gives you a way to
look it up][variable]. We can get a handle to the above class like so:

[variable]: slots-and-handles.html#looking-up-variables

    :::c
    // Load the class into slot 0.
    wrenEnsureSlots(vm, 1);
    wrenGetVariable(vm, "main", "GameEngine", 0);

We could do this every time we call `update()`, but, again, that's kind of slow
because we're looking up "GameEngine" by name each time. A faster solution is to
create a handle to the class once and use it each time:

    :::c
    // Load the class into slot 0.
    wrenEnsureSlots(vm, 1);
    wrenGetVariable(vm, "main", "GameEngine", 0);
    WrenHandle* gameEngine = wrenGetSlotHandle(vm, 0);

Now, each time we want to call a method on GameEngine, we store that value back
in slot zero:

    :::c
    wrenSetSlotHandle(vm, 0, gameEngine);

Just like we hoisted `wrenMakeCallHandle()` out of our performance critical
loop, we can hoist the call to `wrenGetVariable()` out. Of course, if your code
isn't performance critical, you don't have to do this.

### Passing arguments

We've got a receiver in slot zero now, next we need to pass in any other
arguments. In our GameEngine example, that's just the elapsed time. The
remaining arguments go in adjacent slots, right after the receiver. So our one
elapsed time goes into slot one. You can use any of the slot functions to set
this up. For the example, it's just:

    :::c
    wrenSetSlotDouble(vm, 1, elapsedTime);

### Calling the method

We have all of the data in place, so all that's left is to pull the trigger and
tell the VM to start running some code. There's one more function to call:

    :::c
    WrenInterpretResult wrenCall(WrenVM* vm, WrenHandle* method);

It takes the method handle we created using `wrenMakeCallHandle()`. It assumes
you have already set up the receiver and arguments in the slot array.
Critically, it assumes you have as many arguments as the method signature
defines. If you call a method like `takeThree(_,_,_)` and don't put three
arguments in the slot array, bad things will happen.

Now Wren starts running code. It looks up the method on the receiver, executes
it and keeps running until either the method returns or a fiber [suspends][].

[suspends]: ../modules/core/fiber.html#fiber.suspend()

`wrenCall()` returns the same WrenInterpretResult enum to tell you if the method
completed successfully or a runtime error occurred.

### Getting the return value

When `wrenCall()` returns, it leaves the slot array in place. In slot zero, you
can find the method's return value, which you can access using any of the slot
reading functions. If you don't need the return value, you can ignore it.

This is how you drive Wren from C, but how do you put control in Wren's hands?
For that, you'll need the next section...

<a class="right" href="calling-c-from-wren.html">Calling C From Wren &rarr;</a>
<a href="slots-and-handles.html">&larr; Slots and Handles</a>