Codea+

Contents

• Class: Thread
• Class: Semaphore
• Class: Promise
• Module: http
• Module: Debugger
• Module: AutoDoc

Class: Thread

Class: Semaphore

Class: Promise

Module: http

Module: Debugger

Module: AutoDoc

Class: Thread

Thread (func)

Thread constructor.

Parameters:

• func Function to execute on the new thread.

Usage:

• function setup()
      -- Start a thread that will print its value once per frame
      Thread(function()
  
          -- Our thread local counter
          local i = 0
  
          -- Loop forever
          while true do
  
              -- Print and increment counter
              print("Thread counter", i)
              i = i + 1
              
              -- Yield the thread to stop execution for the current frame
              yield()
          end
      end)
  end

Thread.runOnMain (func, ...)

Immediately executes the given function on the main thread.

Various Codea functions do not function correctly when used from a coroutine so use this to temporarily hand execution back to the main thread.

Parameters:

• func Function to run on the main thread.
• ... Parameters to supply to the provided function.

Usage:

• -- Takes a screenshot from the main thread.
  Thread.runOnMain(function()
      screenshot = viewer.snapshot()
  end)

• -- Prints a message from the main thread.
  Thread.runOnMain(print, "Hello main thread!")

Thread.callback (func, ignoreDebugger)

Wraps a function to ensure it is executed on a thread.

By default wrapped functions will not execute (or be queued) if the debugger is active. Set ignoreDebugger to true if the callback should be executed regardless of the debugger.

Parameters:

• func The function to be wrapped.
• ignoreDebugger If true then the function will execute regardless of the state of the debugger.

Returns:

The wrapped function.

Usage:

• local function success(data, statusCode, headers)
      print(statusCode)
  end
  
  -- If this weren't wrapped, we couldn't call
  -- dbg() from inside the callback
  local failure = Thread.callback(function(err)
      print(err)
      dbg()
  end)
  
  Thread.runOnMain(
      http.request,
      "https://codeawebrepo.co.uk/manifest.json",
      success, failure
  )

Thread.wrapMain (func)

Wraps a function to ensure it is executed on the main thread.

Parameters:

• func The function to wrap.

Returns:

The wrapped function

Thread.current ()

Get the current thread.

Returns:

The currently running thread, or nil if the main thread is running.

Thread.allThreads ()

Get all active threads.

Returns:

A table containing all active threads.

Thread.sleep (duration)

Put the current thread to sleep for a period of time.

Parameters:

• duration Duration of sleep in seconds

yield (fast)

Yield execution on the current thread.
This allows cooperative multitasking during a frame & across frames.

Parameters:

• fast (default false)
  When false, execution will not resume on this thread until the next frame at the earliest.
  When true, execution can return to this thread in the current frame.

Class: Semaphore

Semaphore ()

Semaphore constructor.

Semaphore:signal ()

Increments the semaphore value.

Semaphore:signalAll ()

Increase the semaphore value by the number of threads currently waiting on this semaphore.

Semaphore:wait (fast)

Yield the current thread until the semaphore value is > 0.
This will return immediately if the semaphore value is already > 0.

Parameters:

• fast (default false)
  When false, execution will not resume on this thread until the next frame at the earliest.
  When true, execution can return to this thread in the current frame.

Class: Promise

Promise (func)

Promise constructor.

Parameters:

• func Function to execute on a new thread. This function should accept 2 parameters, resolve & reject.

Returns:

New Promise object

Promise:resolve (...)

Resolve the promise with the provided values.

Parameters:

• ... values to resolve the promise with. These will be passed to any chained promises.

Promise:reject (err)

Reject the promise with the provided error.

Parameters:

• err Error to reject the promise with. This will be passed to any chained promises.

Promise:next (onFullfilled, onRejected)

Chain handler functions to be called when the promise is resolved.
The next() method returns a Promise. It takes up to two arguments: callback functions for the success and failure cases of the Promise.

Parameters:

• onFullfilled (optional) A Function called if the Promise is fulfilled. This function can have multiple arguments, the fulfillment values. If it is not a function, it is internally replaced with an "Identity" function (it returns the received argument).
• onRejected (optional) A Function called if the Promise is rejected. This function has one argument, the rejection reason. If it is not a function, it is internally replaced with a "Thrower" function (it throws an error it received as argument).

Returns:

A new promise to be resolved with the result of onFullfilled or onRejected.

Promise:catch (onRejected)

Promise:finally (onFinally)

Promise.all (promises)

Promise:await (fast)

async (func)

Returns a wrapped function that when called will return a promise.

The called function will be executed asynchronously on a new thread and the returned promise will be resolved with the result of the function call.

This allows any function to be turned into an asynchronous function with little effort.

Parameters:

• func The function to be wrapped.

Returns:

The wrapped function

await (promise, fast)

Wait for the given promise to resolve.

Parameters:

• promise The promise to wait for.
• fast (default false)
  When false, execution will not resume on this thread until the next frame at the earliest.
  When true, execution can return to this thread in the current frame.

Returns:

The values the promise was resolved with.

Module: http

http.request (url, success, fail, parameters)

Identical to the built-in function but callbacks will be executed on a thread to allow for debugging within the callbacks.

Parameters:

• url URL to request
• success Callback to be executed in the case of a successful request.
• fail Callback to be executed in the case of a failed request.
• parameters Request parameters.

http.requestProm (url, parameters)

Identical to the built-in function but returns results using a Promise object.

Parameters:

• url URL to request
• parameters Request parameters.

Returns:

Promise object that will be resolved or rejected with the results of the request.

http.requestSync (url, parameters)

Identical to the built-in function but blocks waiting until the request completes (success or failure).

Parameters:

• url URL to request
• parameters Request parameters.

Returns:

In the case of a successful request, a table in the form { response, statusCode, headers }
In the case of a failed request, a table in the form { nil, errorMessage }

Module: Debugger

dbg (condition)

Breaks into the debugger. If a condition is provided, the debugger is only triggered if the condition evaluates to true.

Parameters:

• condition (optional) If true, the debugger will be triggered.

c ()

Exit the debugger and continue execution.

Important: This is only to be called manually using the Codea sidepanel while the debugger is active.

l (nameOrLevel, level)

View local variables.

When called with no arguments this prints all local variables at the stack frame of the active 'dbg()' call.

Note: When listed, string values are omitted. Use l("<variable_name>", [stack_level]) to view the full value.

Important: This is only to be called manually using the Codea sidepanel while the debugger is active.

Parameters:

• nameOrLevel (optional) Name of the variable to read OR stack level to list.
• level (optional) Level to search for the given local variable name.

Usage:

• -- Prints all local variables in the current stack frame
  l()

• -- Prints all local variables in the next stack frame up (1 == current frame)
  l(2)

• -- Prints the value of the local variable 'i'
  -- in the first stack frame it is found.
  l("i")

• -- Prints the value of the local variable 'i' in the 3rd stack frame.
  l("i", 3)

sl (name, value, level)

Set a local variable.

Important: This is only to be called manually using the Codea sidepanel while the debugger is active.

t ()

Print the backtrace again.

Important: This is only to be called manually using the Codea sidepanel while the debugger is active.

Module: AutoDoc

AutoDoc (display)

Generates HTML documentation from the current project source and optionally displays it in a Fullscreen webview.

Parameters:

• display (optional) Display a fullscreen webview and do not return to the caller.

Returns:

HTML string

Usage:

• -- Return the generated html to the caller
  local html = AutoDoc()

• AutoDoc(true) -- This never returns