# Module `coroutine`

Coroutine Manipulation.

The operations related to coroutines comprise a sub-library of the basic library and come inside the table coroutine. See http://www.lua.org/manual/5.1/manual.html#2.11 for a general description of coroutines.

## Type `coroutine`

coroutine.create(f) | Creates a new coroutine, with body `f`.
coroutine.resume(co, ...) | Starts or continues the execution of coroutine `co`.
coroutine.running() | Returns the running coroutine, or nil when called by the main thread.

coroutine.status(co)

Returns the status of coroutine `co`, as a string: `"running"`, if the coroutine is running (that is, it called `status`); `"suspended"`, if the coroutine is suspended in a call to `yield`, or if it has not started running yet; `"normal"` if the coroutine is active but not running (that is, it has resumed another coroutine); and `"dead"` if the coroutine has finished its body function, or if it has stopped with an error.

coroutine.wrap(f, ...) | Creates a new coroutine, with body `f`.
coroutine.yield(...) | Suspends the execution of the calling coroutine.

## Type `coroutine`

### Field(s)

coroutine.create(f)

  Creates a new coroutine, with body `f`.

  `f` must be a Lua function. Returns this new coroutine, an object with type `"thread"`.

  ### Parameter

  - `f` : a function used as coroutine body.

  ### Return value

  #thread: a new coroutine.

coroutine.resume(co, ...)

  Starts or continues the execution of coroutine `co`.

  The first time you resume a coroutine, it starts running its body. The values `val1`, ... are passed as the arguments to the body function. If the coroutine has yielded, `resume` restarts it; the values `val1`, ... are passed as the results from the yield.

  If the coroutine runs without any errors, `resume` returns true plus any values passed to `yield` (if the coroutine yields) or any values returned by the body function (if the coroutine terminates). If there is any error, `resume` returns false plus the error message.

  ### Parameters

  - `#thread co` : coroutine to start or resume.

  - `...` : arguments passed to the body function or as result of yield call.

  ### Return values

  1. #boolean: true plus any values passed to `yield` (if the coroutine yields) or any values returned by the body function (if the coroutine terminates)

  2. #boolean: false plus an error message.

coroutine.running()

  Returns the running coroutine, or nil when called by the main thread.

  ### Return value

  #thread: the running coroutine, or nil when called by the main thread.

coroutine.status(co)

  Returns the status of coroutine `co`, as a string: `"running"`, if the coroutine is running (that is, it called `status`); `"suspended"`, if the coroutine is suspended in a call to `yield`, or if it has not started running yet; `"normal"` if the coroutine is active but not running (that is, it has resumed another coroutine); and `"dead"` if the coroutine has finished its body function, or if it has stopped with an error.

  ### Parameter

  - `#thread co` : a coroutine

  ### Return value

  #string: the status : `"running"`, `"suspended"`, `"normal"` or `"dead"`.

coroutine.wrap(f, ...)

  Creates a new coroutine, with body `f`.

  `f` must be a Lua function. Returns a function that resumes the coroutine each time it is called. Any arguments passed to the function behave as the extra arguments to `resume`. Returns the same values returned by `resume`, except the first boolean. In case of error, propagates the error.

  ### Parameters

  - `f` : a function used as coroutine body.

  - `...` : arguments passed to the body function or as result of yield call.

  ### Return value

  Any values passed to `yield` (if the coroutine yields) or any values returned by the body function (if the coroutine terminates).

coroutine.yield(...)

  Suspends the execution of the calling coroutine.

  The coroutine cannot be running a C function, a metamethod, or an iterator. Any arguments to `yield` are passed as extra results to `resume`.

  ### Parameter

  - `...` : arguments passed as extra results to `resume` function.

  ### Return value

  Any values passed to the `resume` function.