^title Fiber Class
A lightweight coroutine. [Here][fibers] is a gentle introduction.
[fibers]: ../../concurrency.html
## Static Methods
### Fiber.**abort**(message)
Raises a runtime error with the provided message:
<pre class="snippet">
Fiber.abort("Something bad happened.")
</pre>
If the message is `null`, does nothing.
### Fiber.**current**
The currently executing fiber.
### Fiber.**new**(function)
Creates a new fiber that executes `function` in a separate coroutine when the
fiber is run. Does not immediately start running the fiber.
<pre class="snippet">
var fiber = Fiber.new {
System.print("I won't get printed")
}
</pre>
`function` must be a function (an actual [Fn][] instance, not just an object
with a `call()` method) and it may only take zero or one parameters.
[fn]: fn.html
### Fiber.**suspend**()
Pauses the current fiber, and stops the interpreter. Control returns to the
host application.
Typically, you store a reference to the fiber using `Fiber.current` before
calling this. The fiber can be resumed later by calling or transferring to that
reference. If there are no references to it, it is eventually garbage collected.
Much like `yield()`, returns the value passed to `call()` or `transfer()` when
the fiber is resumed.
### Fiber.**yield**()
Pauses the current fiber and transfers control to the parent fiber. "Parent"
here means the last fiber that was started using `call` and not `transfer`.
<pre class="snippet">
var fiber = Fiber.new {
System.print("Before yield")
Fiber.yield()
System.print("After yield")
}
fiber.call() //> Before yield
System.print("After call") //> After call
fiber.call() //> After yield
</pre>
When resumed, the parent fiber's `call()` method returns `null`.
If a yielded fiber is resumed by calling `call()` or `transfer()` with an
argument, `yield()` returns that value.
<pre class="snippet">
var fiber = Fiber.new {
System.print(Fiber.yield()) //> value
}
fiber.call() // Run until the first yield.
fiber.call("value") // Resume the fiber.
</pre>
If it was resumed by calling `call()` or `transfer()` with no argument, it
returns `null`.
If there is no parent fiber to return to, this exits the interpreter. This can
be useful to pause execution until the host application wants to resume it
later.
<pre class="snippet">
Fiber.yield()
System.print("this does not get reached")
</pre>
### Fiber.**yield**(value)
Similar to `Fiber.yield` but provides a value to return to the parent fiber's
`call`.
<pre class="snippet">
var fiber = Fiber.new {
Fiber.yield("value")
}
System.print(fiber.call()) //> value
</pre>
## Methods
### **call**()
Starts or resumes the fiber if it is in a paused state. Equivalent to:
<pre class="snippet">
fiber.call(null)
</pre>
### **call**(value)
Start or resumes the fiber if it is in a paused state. If the fiber is being
started for the first time, and its function takes a parameter, `value` is
passed to it.
<pre class="snippet">
var fiber = Fiber.new {|param|
System.print(param) //> begin
}
fiber.call("begin")
</pre>
If the fiber is being resumed, `value` becomes the returned value of the fiber's
call to `yield`.
<pre class="snippet">
var fiber = Fiber.new {
System.print(Fiber.yield()) //> resume
}
fiber.call()
fiber.call("resume")
</pre>
### **error**
The error message that was passed when aborting the fiber, or `null` if the
fiber has not been aborted.
<pre class="snippet">
var fiber = Fiber.new {
123.badMethod
}
fiber.try()
System.print(fiber.error) //> Num does not implement method 'badMethod'.
</pre>
### **isDone**
Whether the fiber's main function has completed and the fiber can no longer be
run. This returns `false` if the fiber is currently running or has yielded.
### **try**()
Tries to run the fiber. If a runtime error occurs
in the called fiber, the error is captured and is returned as a string.
<pre class="snippet">
var fiber = Fiber.new {
123.badMethod
}
var error = fiber.try()
System.print("Caught error: " + error)
</pre>
If the called fiber raises an error, it can no longer be used.
### **try**(value)
Tries to run the fiber. If a runtime error occurs
in the called fiber, the error is captured and is returned as a string.
If the fiber is being
started for the first time, and its function takes a parameter, `value` is
passed to it.
<pre class="snippet">
var fiber = Fiber.new {|value|
value.badMethod
}
var error = fiber.try("just a string")
System.print("Caught error: " + error)
</pre>
If the called fiber raises an error, it can no longer be used.
### **transfer**()
**TODO**
### **transfer**(value)
**TODO**
### **transferError**(error)
**TODO**