Support Direct Linking

[stmonty]

Direct Linking

We want to support direct linking Jank modules for more efficient function invocation. In Jank, function's are called through their vars, but with direct linking this indirection will be removed for the module that was compiled with the direct linking optimization.

The removal of this indirection will increase the efficiency of the compiled module. Compiling Jank's clojure.core will be a good example of a module that can gain speed improvements through direct linking.

Drawback

The main drawback of direct linking is that it limits the dynamic nature of Jank as redefining a var won't automatically change all the call-sites to use the new var. This can be mitigated by marking a var with ^:dynamic or ^:redef but this use case won't be supported for now.

Implementation Plan

The plan is to add a new compilation flag -fdirect-linking that when set would change the IR generation.

The main IR functions that are currently used are jank_deref for derefing the var to get the function ptr and then performing jank_call with the function pointer and arguments.

How it looks now:

define ptr @clojure_core_add_7604_2(ptr %a, ptr %b) {
entry:
  %0 = load ptr, ptr @var_clojure.core_SLASH__PLUS_, align 8
  %1 = call ptr @jank_deref(ptr %0)
  %2 = call ptr @jank_call2(ptr %1, ptr %a, ptr %b)
  ret ptr %2
}

The idea would be to simplify this by not requiring the loading of the var and the need to dereference it. Instead we would still have a global var and a single dereference to get the function pointer and use the function pointer directly in the call. This will be the first pass.

The IR would then look like this, with @0 representing the global derefed function pointer:

define ptr @clojure_core_add_7604_2(ptr %a, ptr %b) {
entry:
  %0 = call ptr @jank_call2(ptr @0, ptr %a, ptr %b)
  ret ptr %0
}

For non-variadic functions, at compile time, all the call-sites for a function will be replaced with the static call to the function pointer. The var will still exist in the global namespace map. Variadic functions will still use a call to jank_call<n>.

For non-variadic functions, the IR would then look like this at the function call site:

define ptr @clojure_core_add_7604_2(ptr %a, ptr %b) {
entry:
  %0 = call ptr @clojure_core__PLUS__1234_2(ptr %a, ptr %b)
  ret ptr %0
}

[stmonty]

Table of Contents

1. Use Cases
   1. Single Module (eval)
      1. Where to put var_root global?
   2. Single Module (AoT)
      1. Where to put the var_root global?
   3. Evaling a Module that has AoT dependency
      1. Where to put the var_root global?
   4. AoT compiling a module that has an AoT dependency
      1. Where to put the var_root global?
      2. This is the simple case
   5. Sinister Case - AoT compiled module w/ AoT compiled dependency
      1. Where to put the var_root global?
   6. Special Case - One top level form introduces multiple vars
      1. Where to put the var_root global?

Use Cases

Single Module (eval)

A single module that is being evaled, top to bottom, one top level form at a time. N IR modules = N Top level forms

(defn foo [])
(defn bar []
  (foo))

Where to put var_root global?

In the second top level form (defn bar) we want to put it in the global ctor. Deref var_clojure_core_SLASH_foo and initialize the var_root global in the global ctor.

It is safe to do this because the var was created in the previous IR module when the first form was evaled.

./build/jank run --fdirect-linking ./scripts/case1.jank

Single Module (AoT)

A single module that is being AoT compiled. 1 IR module.

(defn foo [])
(defn bar []
  (foo))

./build/jank compile --module-path=./scripts/ --fdirect-linking case1

Where to put the var_root global?

You want to generate the global in the gen(def) code in jank_load function, after jank_var_bind_root.
Storing the global as soon as you def is storing the global as soon as you can (as soon as it could be used).

Evaling a Module that has AoT dependency

A module is being evaled one top level form at a time, but has a dependency that was AoT compiled (think clojure.core)
N + 1 IR modules = N top level forms + 1 IR module from the dependency

(require 'util)

(defn bar []
  (util/foo))

Where to put the var_root global?

In the second top level form (defn bar) we want to put it in the global ctor. Deref var_clojure_core_SLASH_foo and initialize the var_root global in the global ctor.

It is safe to do this because the var was created in the previous IR module when the first form was evaled.

AoT compiling a module that has an AoT dependency

Self explanatory - 2 IR modules , one for each compiled module

(require 'util)
(util/foo)

In this example, imagine this ns is core. The jank_load_core function in the IR would run all the top level effects.
(require) is run in the jank_load_core. Global ctor runs first, and then jank_load_core.

Where to put the var_root global?

We can't do it in the global ctor block.
We COULD do it in jank_load_core only immediately AFTER the (require). It has to be immediately after because it needs to be before any potential uses.

It doesn't need to go immediately after…
If we instead put it before the first usage. In other words, if we lazily initialize it.

The problem with require is that it is just a function call, and there is no way to figure out when it is called.

Instead, what if we say "oh we are trying to use util/foo, have we already initialized the var_root for that global? If not, lets generate the IR to generate that now in the jank_load function, and then generate the code that actually uses the global".

On the first usage, we jump back to jank_load and perform the deref on the var and store the value into the root.

This is the simple case

We have a top level usage of util/foo so it will be in jank_load_core so it will easy to find the first usage.

Sinister Case - AoT compiled module w/ AoT compiled dependency

(require 'util)

(defn bar []
  (util/foo))

Where to put the var_root global?

We don't know when core/bar is going to be called.

AoT compilation is done in two passes.

• First pass = eval the top level forms
• After we have evaled the whole file, we check, are we AoT compiling?
  If so, then take all of the expressions and we generate a brand new IR module and that IR module has the jank_load function.

We will do the IR gen for jank_load
Then, when we hit (defn bar) we are going to make a new nested LLVM processor.
When we process bar and we detect the usage of util/foo, then we generate the store for the var_root. The problem is we are processing the bar function, but the codegen needs to be in the jank_load function.

We put it before the codegen for defn bar in jank_load_core.

1. Implementation details

   Need a way to pass information up.

Special Case - One top level form introduces multiple vars

These vars want to be direct-linked, but they have not been initialized while we did codegen

(do
  (defn foo [])
  (defn bar []
    (foo)))

Where to put the var_root global?

Is it safe?