Fiber.cs

Go to the documentation of this file.

/*

Author: Aaron Oneal, http://aarononeal.info

Copyright (c) 2012 Spicy Pixel, http://spicypixel.com

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

*/
using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;
using System.Threading;

namespace SpicyPixel.Threading
{
    public partial class Fiber
    {
        [ThreadStatic]
        private static Fiber currentFiber;

        private static FiberFactory fiberFactory = new FiberFactory ();

        private static int nextId = 0;

        private IEnumerator coroutine;

        private Action action;
        private Action<object> actionObject;
        private object objectState;

        private Func<FiberInstruction> func;
        private Func<object, FiberInstruction> funcObject;

        private FiberScheduler scheduler;
        private int status = (int)FiberStatus.Created;
        // must be int to work with Interlocked on Mono
        private IDictionary<string, object> properties;

        internal CancellationToken cancelToken;
        internal Fiber antecedent;
        internal Queue<FiberContinuation> continuations;

        public static Fiber CurrentFiber {
            get {
                return currentFiber;
            }
            private set {
                currentFiber = value;
            }
        }

        public static FiberFactory Factory {
            get {
                return fiberFactory;
            }
        }

        static int CheckTimeout (TimeSpan timeout)
        {
            try {
                return checked((int)timeout.TotalMilliseconds);
            } catch (System.OverflowException) {
                throw new ArgumentOutOfRangeException ("timeout");
            }
        }

        public IDictionary<string, object> Properties {
            get {
                if (properties == null)
                    properties = new Dictionary<string, object> ();

                return properties;
            }
        }

        internal FiberScheduler Scheduler {
            get { return scheduler; }
            set { scheduler = value; }
        }

        public string Name { get; set; }

        public object ResultAsObject { get; internal set; }

        public bool IsCanceled {
            get {
                return (FiberStatus)status == FiberStatus.Canceled;
            }
        }

        public bool IsCompleted {
            get {
                return (FiberStatus)status >= FiberStatus.RanToCompletion;
            }
        }

        public bool IsFaulted {
            get {
                return (FiberStatus)status == FiberStatus.Faulted;
            }
        }

        public Exception Exception {
            get;
            private set;
        }

        public FiberStatus Status {
            get { return (FiberStatus)status; }
            set { status = (int)value; }
        }

        public Fiber Antecedent {
            get { return antecedent; }
        }

        public CancellationToken CancellationToken {
            get { return cancelToken; }
        }

        private void FinishCompletion ()
        {
            if (continuations == null)
                return;

            while (true) {
                if (continuations.Count == 0)
                    return;

                var continuation = continuations.Dequeue ();
                continuation.Execute ();
            }
        }

        internal void CancelContinuation ()
        {
            status = (int)FiberStatus.Canceled;
            FinishCompletion ();
        }

        internal void FaultContinuation (Exception exception)
        {
            status = (int)FiberStatus.Faulted;
            Exception = exception;
            FinishCompletion ();
        }

        public int Id { get; private set; }

        public Fiber (IEnumerator coroutine) : this (coroutine, CancellationToken.None)
        {
        }

        public Fiber (IEnumerator coroutine, CancellationToken cancellationToken)
        {
            Id = nextId++;
            this.coroutine = coroutine;
            this.cancelToken = cancellationToken;
        }

        public Fiber (Action action) : this (action, CancellationToken.None)
        {
        }

        public Fiber (Action action, CancellationToken cancellationToken)
        {
            Id = nextId++;
            this.action = action;
            this.cancelToken = cancellationToken;
        }

        public Fiber (Action<object> action, object state) : this (action, state, CancellationToken.None)
        {
        }

        public Fiber (Action<object> action, object state, CancellationToken cancellationToken)
        {
            Id = nextId++;
            this.actionObject = action;
            this.objectState = state;
            this.cancelToken = cancellationToken;
        }

        public Fiber (Func<FiberInstruction> func) : this (func, CancellationToken.None)
        {
        }

        public Fiber (Func<FiberInstruction> func, CancellationToken cancellationToken)
        {
            Id = nextId++;
            this.func = func;
            this.cancelToken = cancellationToken;
        }

        public Fiber (Func<object, FiberInstruction> func, object state) : this (func, state, CancellationToken.None)
        {
        }

        public Fiber (Func<object, FiberInstruction> func, object state, CancellationToken cancellationToken)
        {
            Id = nextId++;
            this.funcObject = func;
            this.objectState = state;
            this.cancelToken = cancellationToken;
        }

        public void Start ()
        {
            Start (FiberScheduler.Current);
        }

        public void Start (FiberScheduler scheduler)
        {
            // It would be unusual to attempt to start a Fiber more than once,
            // but to be safe and to support calling from any thread
            // use Interlocked with boxing on the enum.

            var originalState = (FiberStatus)Interlocked.CompareExchange (ref status, (int)FiberStatus.WaitingToRun, (int)FiberStatus.Created);
            if (originalState != FiberStatus.Created) {
                originalState = (FiberStatus)Interlocked.CompareExchange (ref status, (int)FiberStatus.WaitingToRun, (int)FiberStatus.WaitingForActivation);
                if (originalState != FiberStatus.WaitingForActivation) {
                    throw new InvalidOperationException ("A fiber cannot be started again once it has begun running or has completed.");
                }
            }

            this.scheduler = scheduler;
            ((IFiberScheduler)this.scheduler).QueueFiber (this);
        }

        public void ThrowIfCanceled ()
        {
            if (IsCanceled)
                throw new System.Threading.OperationCanceledException ();
        }

        public void ThrowIfFaulted ()
        {
            if (IsFaulted)
                throw Exception;
        }

        public void ThrowIfCanceledOrFaulted ()
        {
            ThrowIfCanceled ();
            ThrowIfFaulted ();
        }

        internal FiberInstruction Execute ()
        {
            //Console.WriteLine ("Fiber {0}:{1} start executing", Id, Status);

            // Sanity check the scheduler. Since this is a scheduler
            // only issue, this test happens first before execution
            // and before allowing an exception handler to take over.
            if (IsCompleted)
                throw new InvalidOperationException ("An attempt was made to execute a completed Fiber. This indicates a logic error in the scheduler.");

            // Setup thread globals with this scheduler as the owner.
            // The sync context is also setup when the scheduler changes.
            // Setting the sync context isn't a simple assign in .NET
            // so don't do this until needed.
            //
            // Doing this setup in Execute() frees derived schedulers from the 
            // burden of setting up the sync context or scheduler. It also allows the
            // current scheduler to change on demand when there is more than one
            // scheduler running per thread. 
            // 
            // For example, each MonoBehaviour in Unity is assigned its own
            // scheduler since the behavior determines the lifetime of tasks.
            // The active scheduler then can vary depending on which behavior is 
            // currently executing tasks. Unity will decide outside of this framework 
            // which behaviour to execute in which order and therefore which 
            // scheduler is active. The active scheduler in this case can 
            // only be determined at the time of fiber execution.
            //
            // Unlike CurrentFiber below, this does not need to be stacked
            // once set because the scheduler will never change during fiber
            // execution. Only something outside of the scheduler would
            // change the scheduler.
            if (FiberScheduler.Current != scheduler)
                FiberScheduler.SetCurrentScheduler (scheduler, true);

            // Push the current fiber onto the stack and pop it in finally.
            // This must be stacked because the fiber may spawn another
            // fiber which the scheduler may choose to inline which would result
            // in a new fiber temporarily taking its place as current.
            var lastFiber = Fiber.CurrentFiber;
            Fiber.CurrentFiber = this;

            // Start the fiber if not started
            Interlocked.CompareExchange (ref status, (int)FiberStatus.WaitingToRun, (int)FiberStatus.Created);
            Interlocked.CompareExchange (ref status, (int)FiberStatus.Running, (int)FiberStatus.WaitingToRun);

            try {
                object result = null;

                // Execute the coroutine or action
                if (coroutine != null) {
                    //Console.WriteLine ("Fiber {0}:{1} start executing coroutine", Id, Status);
                    // Execute coroutine
                    if (coroutine.MoveNext ()) {
                        // Get result of execution
                        result = coroutine.Current;

                        // If the coroutine returned a stop directly
                        // the fiber still needs to process it
                        if (result is StopInstruction)
                            Stop (FiberStatus.RanToCompletion);
                    } else {
                        // Coroutine finished executing
                        result = Stop (FiberStatus.RanToCompletion);
                    }
                    //Console.WriteLine ("Fiber {0}:{1} end executing coroutine", Id, Status);
                } else if (action != null) {
                    // Execute action
                    action ();

                    // Action finished executing
                    result = Stop (FiberStatus.RanToCompletion);
                } else if (actionObject != null) {
                    // Execute action
                    actionObject (objectState);

                    // Action finished executing
                    result = Stop (FiberStatus.RanToCompletion);
                } else if (func != null) {
                    result = func ();
                    func = null;

                    if (result is StopInstruction)
                        Stop (FiberStatus.RanToCompletion);
                } else if (funcObject != null) {
                    result = funcObject (objectState);
                    funcObject = null;

                    if (result is StopInstruction)
                        Stop (FiberStatus.RanToCompletion);
                } else {
                    // Func execution nulls out the function
                    // so the scheduler will return to here
                    // when complete and then stop.
                    result = Stop (FiberStatus.RanToCompletion);
                }

                // Treat null as a special case
                if (result == null)
                    return FiberInstruction.YieldToAnyFiber;

                // Return instructions or throw if invalid
                var instruction = result as FiberInstruction;
                if (instruction == null) {
                    // If the result was an enumerator there is a nested coroutine to execute
                    if (result is IEnumerator) {
                        instruction = new YieldUntilComplete (Fiber.Factory.StartNew (result as IEnumerator, cancelToken, scheduler));
                    } else if (result is Fiber) {
                        // Convert fibers into yield instructions
                        instruction = new YieldUntilComplete (result as Fiber);
                    } else {
                        // Pass through other values
                        return new ObjectInstruction (result);
                    }
                }

                if (instruction is FiberResult) {
                    ResultAsObject = ((FiberResult)instruction).Result;
                    result = Stop (FiberStatus.RanToCompletion);
                }

                // Verify same scheduler    
                if (instruction is YieldUntilComplete && ((YieldUntilComplete)instruction).Fiber.Scheduler != FiberScheduler.Current)
                    throw new InvalidOperationException ("Currently only fibers belonging to the same scheduler may be yielded to. FiberScheduler.Current = "
                    + (FiberScheduler.Current == null ? "null" : FiberScheduler.Current.ToString ())
                    + ", Fiber.Scheduler = " + (((YieldUntilComplete)instruction).Fiber.Scheduler == null ? "null" : ((YieldUntilComplete)instruction).Fiber.Scheduler.ToString ()));

                var yieldToFiberInstruction = instruction as YieldToFiber;
                if (yieldToFiberInstruction != null) {
                    // Start fibers yielded to that aren't running yet
                    Interlocked.CompareExchange (ref yieldToFiberInstruction.Fiber.status, (int)FiberStatus.WaitingToRun, (int)FiberStatus.Created);
                    var originalState = (FiberStatus)Interlocked.CompareExchange (ref yieldToFiberInstruction.Fiber.status, (int)FiberStatus.Running, (int)FiberStatus.WaitingToRun);
                    if (originalState == FiberStatus.WaitingToRun)
                        yieldToFiberInstruction.Fiber.scheduler = scheduler;

                    // Can't switch to completed fibers
                    if (yieldToFiberInstruction.Fiber.IsCompleted)
                        throw new InvalidOperationException ("An attempt was made to yield to a completed fiber.");

                    // Verify scheduler
                    if (yieldToFiberInstruction.Fiber.Scheduler != FiberScheduler.Current)
                        throw new InvalidOperationException ("Currently only fibers belonging to the same scheduler may be yielded to. FiberScheduler.Current = "
                        + (FiberScheduler.Current == null ? "null" : FiberScheduler.Current.ToString ())
                        + ", Fiber.Scheduler = " + (yieldToFiberInstruction.Fiber.Scheduler == null ? "null" : yieldToFiberInstruction.Fiber.Scheduler.ToString ()));
                }

                //Console.WriteLine ("Fiber {0}:{1} returning {2}", Id, Status, instruction);
                return instruction;
            } catch (System.Threading.OperationCanceledException cancelException) {
                // Handle as proper cancellation only if the token matches.
                // Otherwise treat it as a fault.
                if (cancelException.CancellationToken == cancelToken) {
                    this.Exception = null;
                    return Stop (FiberStatus.Canceled);
                } else {
                    this.Exception = cancelException;
                    return Stop (FiberStatus.Faulted);
                }
            } catch (Exception fiberException) {
                this.Exception = fiberException;
                return Stop (FiberStatus.Faulted);
            } finally {
                // Pop the current fiber
                Fiber.CurrentFiber = lastFiber;

                //Console.WriteLine ("Fiber {0}:{1} end executing", Id, Status);
            }
        }

        private StopInstruction Stop (FiberStatus finalStatus)
        {
            // Interlocked isn't necessary because we don't need
            // the initial value (stops are final). They are also
            // only called by the scheduler thread during Execute().
            status = (int)finalStatus;
            FinishCompletion ();
            return FiberInstruction.Stop;
        }
    }
}