Library coroutine

Coroutine library. Allows for co-operative threading.

Functions

create( func ) Creates and returns a coroutine thread object from the given function.
resume( thread, ... ) Resumes a given coroutine.
running() Returns the current running coroutine, or nil if none is running.
status( thread ) Gets the status of a given coroutine.
wait( durationInSeconds ) Yields the current coroutine and will continue to yield when called until the given time has elapsed (relative to time.curTime()).
wrap( func ) Returns a function that, when invoked, resumes the coroutine representing the given function, passing the provided arguments.
yield( ... ) Yields the current coroutine, suspending it in place ready for the next resume.


Functions

coroutine.create( func )
Creates and returns a coroutine thread object from the given function.

Environment:

Shared

Parameters:

  • (function) func: Function to run inside the coroutine.

Usage:

    -- Create a new thread that does some work. 
    local Thread = coroutine.create( function( Message ) 
    	print( "Caller says:", Message ) 
    	local Reply = coroutine.yield( "Hello!" ) 
    	print( "Caller says:", Reply ) 
    	return "Goodbye!" 
    end ) 
    local Success, Message = coroutine.resume( Thread, "Hello thread!" ) 
    assert( Success ) 
    print( "Coroutine says:", Message ) 
    Success, Message = coroutine.resume( Thread, "Goodbye thread!" ) 
    assert( Success ) 
    print( "Coroutine says:", Message ) 
    -- Coroutine is now dead as its function has returned.

Return value:

    (thread) Coroutine object representing the given function.
coroutine.resume( thread, ... )
Resumes a given coroutine.

Environment:

Shared

Parameters:

  • (thread) thread: Coroutine to resume.
  • (Any...) ...: The parameters to pass to the coroutine (as the initial arguments, or to be returned by coroutine.yield()).

Usage:

    -- Pass some data to a thread and retrieve its next yielded response. 
    local Success, Data = coroutine.resume( Thread, { Message = "Hello thread!" } ) 
    -- This data will be taken from the next coroutine.yield() or return statement in the thread. 
    print( Data )

Return values:

  1. (boolean) True if the coroutine executed without error, false if an error was caught.
  2. (Any...) If the coroutine errored, the error that was thrown. Otherwise, all values passed to coroutine.yield() or returned by the coroutine's function.
coroutine.running()
Returns the current running coroutine, or nil if none is running.

Environment:

Shared

Usage:

    -- Within a coroutine body, it's possible to get the running thread. 
    coroutine.wrap( function() 
    	local Thread = coroutine.running() 
    	print( coroutine.status( Thread ) ) -- "running" 
    end )() 
    -- Outside of a coroutine, there is no running thread. 
    print( coroutine.running() ) -- nil
coroutine.status( thread )
Gets the status of a given coroutine. Either 'suspended', 'running', 'normal' or 'dead'.

Environment:

Shared

Parameters:

  • (thread) thread: Coroutine to check.

Usage:

    -- New coroutines are suspended. 
    local Thread = coroutine.create( function() end ) 
    print( coroutine.status( Thread ) ) -- "suspended"

Return value:

    (string) The status of the given coroutine.
coroutine.wait( durationInSeconds )
Yields the current coroutine and will continue to yield when called until the given time has elapsed (relative to time.curTime()). This does not resume the coroutine for you after the given time. You must keep resuming it until the time has elapsed (e.g. in a think hook or repeating timer).

Environment:

Shared

Parameters:

  • (number) durationInSeconds: The time in seconds to yield for.

Usage:

    -- Every second, print the next number in the sequence. 
    local Thread = coroutine.create( function() 
    	local i = 1 
    	while true do 
    		coroutine.wait( 1 ) 
    		print( i ) 
    		i = i + 1 
    	end 
    end ) 
    -- Poll the coroutine to allow it to advance time. 
    hook.add( "think", "coroutine_counter", function() coroutine.resume( Thread ) end )
coroutine.wrap( func )
Returns a function that, when invoked, resumes the coroutine representing the given function, passing the provided arguments. The returned values from the wrapped function represent the values that were yielded from the coroutine, or returned at the end.

Environment:

Shared

Parameters:

  • (function) func: Function to run inside the coroutine.

Usage:

    -- Generate an iterator over powers of 2 using a coroutine-wrapped function. 
    -- Each invocation in a generic for will resume the coroutine. 
    local function PowersOf2( Start, End ) 
    	return coroutine.wrap( function() 
    		for i = Start, End do 
    			coroutine.yield( bit.lshift( 1, i ) ) 
    		end 
    	end ) 
    end 
    -- This will print every power of 2 between 2 ^ 1 and 2 ^ 10 (inclusive). 
    for PowerOf2 in PowersOf2( 1, 10 ) do 
    	print( PowerOf2 ) 
    end

Return value:

    (function) Function that resumes the coroutine when invoked, returning any yielded/returned values.
coroutine.yield( ... )
Yields the current coroutine, suspending it in place ready for the next resume. Suspended coroutines will not execute again until they are resumed externally.

Environment:

Shared

Parameters:

  • (Any...) ...: The values to yield to the caller, which will be returned by coroutine.resume() (or from calling a coroutine-wrapped function).

Usage:

    -- Yield some data to the caller, and use the data passed through coroutine.resume() afterwards. 
    local Data = coroutine.yield( { Message = "Hello caller!" } ) 
    -- This next line will not execute until the caller resumes the thread again. 
    print( Data )

Return value:

    (Any...) The values passed to coroutine.resume() or a coroutine-wrapped function after this yield.

Valid XHTML 1.0!