Friday, April 22, 2005
Cooperative Fiber Mode Sample
Well it’s been a while since I’ve blogged… There’ve been a few distractions, starting with Beta 1, then vacation, and now things are back to normal. So it seems reasonable to blog about something that we’ve just shipped in Whidbey Beta 1: The cooperative fiber mode sample that’s been included in the SDK. You can get the freely downloadable SDK here. If you load up the documentation, go to the Contents, and select Samples->Application Samples->Cooperative Fiber Mode Application Sample you’ll be able to get to the code.
This sample shows how to write an extremely simple fiber mode host. But it does so with a twist. Instead of scheduling the tasks in a cooperative, automatic, and transparent fashion this sample exposes the concept of fibers to managed code . This allows the managed code author to use fibers as the unmanaged code author would. This results in an implementation that for the most part relies upon native threads. The only time fibers are actually used is when the user explicitly chooses to use them. This closely matches the experience you’d have programming with fibers in the unmanaged world. More sophisticated hosts would want to implement their own synchronization primitives that would schedule other tasks while blocking.
Over the next several blog entries I plan to give a walk through of the new fiber mode sample. During this blog I’ll start with loading the runtime and getting bootstrapped into managed code. But first let me give a brief warning. Fiber mode is complex and hard to get right. You probably don’t want to implement fiber mode into your application on a whim. Weigh your other options carefully before jumping into running in fiber mode.
Loading the runtime hasn’t changed in a significant fashion from v1.0 and v1.1. We start with a call that should be familiar to anyone who has written code to host the runtime before:
// load up the runtime
HRESULT hr = CorBindToRuntimeEx(
NULL, // version of the runtime to request
NULL, // flavor of the runtime to request
0, // runtime startup flags
CLSID_CLRRuntimeHost, // clsid of ICLRRuntimeHost
IID_ICLRRuntimeHost, // IID of ICLRRuntimeHost
(PVOID*)&pClrHost); // a pointer to our punk that we get
The only difference you may notice is that we’re asking for a different interface. Previously we asked for CLSID_CorRuntimeHost and IID_ICorRuntimeHost. In Whidbey we have a brand new interface that let you do much more.
Next, we have a new call:
hr = pClrHost->SetHostControl(static_cast
This new command is handing off to the runtime our IHostControl interface. It’s not a required call for hosting the runtime, but it’s the mechanism through which we provide our threading managers (so it is required for fiber mode). One callback on this API is GetHostManager which when called by the runtime allows the host to provide a manager. The host managers provide threading, memory, assembly loading, or other low level functionality to the runtime. Throughout the next couple of articles I’ll be strictly focused on the threading managers.
After we hand off our host control we’re back to familiar territory again:
hr = pClrHost->Start();
Now the runtime has been started and we can start executing managed code. And the way we start doing this has changed in Whidbey. There are a few different mechanisms, and I’ll mention 2 of them. The first is the app domain manager. This allows a host to have an assembly loaded into every domain, including the default domain. Once this assembly is loaded the host can start running managed code directly from it. The other option is a sample call to execute an assembly passing it a string of arguments. This sample uses the 2nd method as it’s simpler and sufficient for our purposes:
hr = pClrHost->ExecuteInDefaultAppDomain(
curDir, // directory to assembly
L"Microsoft.Samples.FiberBootstrap",// Type name to load
L"EntryPoint", // Method name to execute
bootstrapArgs, // Arguments to be passed in
&retVal); // return value of function
The executed function exists in a separate managed DLL (FiberBootstrap.dll). It simply parses the string and then calls AppDomain.ExecuteAssembly on the current domain. This allows the sample to run any managed assembly you pass to it. This EXE that gets loaded then can interact with the fiber mode APIs.
At this point we’ve loaded the runtime, loaded an assembly into the default domain and executed managed code. That’s really all there is to getting started. If you were a simpler host you wouldn’t even need the SetHostControl call! In the next article I’ll discuss what that SetHostControl call is setting up for us.
In the last blog entry I went over how we start the runtime. Once it was loaded we were running managed code, but I glossed over the managers that were present and participating in running the system. Today we start off with CHostControl::GetHostManager. CHostControl is CoopFiber’s implementation of IHostControl, and GetHostManager is the only API we implement.
HRESULT __stdcall CHostControl::GetHostManager(
/* [in] */ REFIID riid,
/* [out] */ void **ppObject)
if(riid == IID_IHostTaskManager)
if(m_pTaskMan == NULL)
m_pTaskMan = new CHostTaskManager();
*ppObject = static_cast
else if(riid == IID_IHostSyncManager)
if(m_pTaskMan == NULL)
m_pTaskMan = new CHostTaskManager();
*ppObject = static_cast
What are we doing here? CHostControl has one task manager. That task manager actually implements both IHostTaskManager and IHostSyncManager. These are the minimal APIs you need to implement fiber mode of any sort. IHostTaskManager provides the mechanisms for creating tasks. IHostSyncManager provides the mechanisms for providing synchronization between those tasks.
At load time, the CLR calls the host-implemented IHostControl interface and asks for the managers that the CLR knows about. The host can respond by handing back an interface pointer or it can respond by returning E_NOINTERFACE. Virtually any combination of managers is supported. The one gotcha is your thread and synchronization must be compatible. The default synchronization implementation in the CLR is not fiber aware. That’s the reason that we implement both a task and synchronization manager for this fiber mode sample.
Here our GetHostManager implementation simply lazily creates the task manager for the first caller and hands it off to the runtime. If it’s a manager the host doesn’t know about we return E_NOINTERFACE.
The host control also provides a couple of other APIs that we’re not using here. The first is SetAppDomainManager. This is where the host is notified of the creation of an app domain. The host is passed both the ID of the newly created app domain and an IUnknown pointer for the app domain manager. Because CoopFiber doesn’t use an app domain manager we’ll never get any calls here. We simply return E_NOTIMPL.
The other API is GetDomainNeutralAssemblies. This is another API that CoopFiber doesn’t use because it doesn’t care whether assemblies are loaded domain neutral or not. Again, it simply returns E_NOTIMPL.
So that’s it for the host control. Stay tuned for the next entry when I’ll dig into our task manager. Things will start to get really interesting then!
When I last left off we went over the host control. The host control hands off our task and synchronization managers. Now it’s time to take a look at the two host-implemented managers, starting with the task manager.
I’m going to skip over the minor details such as constructors, destructors, etc… and only focus in on the details of the APIs that communicate with the CLR. The APIs we care about the most are GetCurrentTask and CreateTask. A fiber mode host with it’s own scheduler would pay more attention to APIs like Sleep (where we merely call the OS API), SwitchToTask (which is a NOP in CoopFiber), and the other APIs. Because CoopFiber doesn’t have a scheduler we aren’t concerned with these APIs. So if we look at GetCurrentTask:
CHostTask *curTask = CHostTask::GetCurrentTask(false);
// 0x1E00 - value returned by GetCurrentFiber when not a fiber
curTask = CHostTask::CreateTask(ConvertThreadToFiber(NULL),TASK_FLAG_RUNNING);
curTask = CHostTask::CreateTask(GetCurrentFiber(),TASK_FLAG_RUNNING);
*pTask = (IHostTask *)curTask;
We simply check to see if the current task has been created. If it hasn’t we create a new task. Depending on whether or not we’re already running on a fiber (by some chance) we’ll re-use the fiber, otherwise we’ll create a new fiber. Here we choose to allow any random threads that enter into the CLR to be converted to fibers. A host could also deny these threads entrance by returning HOST_E_INVALIDOPERATION.
The other interesting API is CreateTask:
CHostTask *tmp = CHostTask::CreateTask();
if (tmp == NULL)
_ASSERTE(FALSE && "Out of memory in CreateTask!");
*ppTask = (IHostTask *)tmp;
This isn’t really doing anything too fancy. We’re just creating out internal task implementation which implements IHostTask. We’re handing that off to the runtime. Later the runtime will call Start on it and it’ll kick off the running of a new task. We’ll look at the IHostTask implementation next time.
Last time we left off with the CLR calling into the host to create a task. So far everything’s been very simple. For each interface we’ve only needed to implement a couple of methods to get the bulk of the work done. While I’ve certainly left out a couple of lines of code here and there, nearly every other API in the interface merely returns S_OK.
Now things start to get really interesting! The IHostTask interface has just a few functions which are exposed to the runtime. But there’s a lot of other functionality related to the task embedded in here.
We’ll start off at the natural place to start a task: Start. It’s pretty simple:
_ASSERTE(m_fiberAddr == NULL);
m_fiberAddr = ::CreateFiber(0,(LPFIBER_START_ROUTINE )CHostFiberProc,(PVOID)this);
// create the new thread
We create a fiber for the new task, and we create a new thread. This new thread starts in StartNewThread, defined in callbacks.cpp. It looks something like:
CHostTaskManager *myManager = CHostTask::GetManager();
CHostTask *curTask = static_cast
LPVOID fiberAddr = ConvertThreadToFiber(NULL);
BOOL fResult = ConvertFiberToThread();
Here we simply convert the new thread over to fibers, and then switch in the fiber passed as the argument. This brings us back to our CHostTask implementation where we need to look at the SwitchIn logic. This is the most complicated piece of code we’ve encountered yet.
CHostTask *curTask = GetCurrentTask();
_ASSERTE(curTask != this);
// Save our thread handle so we can queue APCs
&m_hCurThread, 0 , FALSE,
m_hCurThread = INVALID_HANDLE_VALUE;
_ASSERTE(!"Duplicate handle failed");
// when the fiber switches back we need to switch in our
// previous task.
HRESULT hr = curTask->m_pCallback->SwitchIn(GetCurrentThread());
// release the ref for TLS from the previous thread
m_hCurThread = INVALID_HANDLE_VALUE;
What’s going on here? We have a couple of things to worry about when switching tasks. We have the task that we’re switching to (this) and we have the task we’re switching from (curTask).
One of the issues we’re concerned with is the lifetime of the task. While it’s running we don’t want it cleaned up, so we hold a reference to it (in Thread Local Store). A more complicated host would probably have a pool of tasks rather than the simple TLS mechanism.
If we need to alert a task we’ll queue an Asynchronous Procedure Call (APC) to it. Therefore the next thing we do is save the current thread’s handle into this task. We’ll use this in IHostTask::Alert. Finally we set the running flag and switch over to the new task.
The interesting thing to note about this method is there are 2 halves to it. After we call SwitchToFiber we are running on a different fiber on a different stack. We’ll only return to the bottom half after someone has switched back to “curTask”. This is the task that we switched away from. When this happens it’s now the bottom half’s job to tell the runtime that “curTask” is once again running.
It’s possible when we get to the bottom half “curTask” was only switched in to exit. If so we’ll notify the runtime and immediately re-run the task we’ve been set to re-run. This is an implementation detail of CoopFiber to allow calling ExitTask on the managed fiber implementation.
We’re nearly done so we clean up the resources we allocated in the top half for “this”. It’s no longer running, so we don’t need a reference to it. Finally we restore the settings for the thread that were stored in the task. These would have been changed when we did the intital SwitchToFiber which either switched in a task that was at the bottom half of SwitchIn, or the top of CHostFiberProc (in callbacks.cpp).
Wow, so that’s how we start a task! We create a new thread, that thread gets converted over to fibers, and we switch in the newly created task (which has a fiber already associated with it). That’ll end up in CHostFiber proc which we’ll cover in a future edition.
There’s just one more detail to cap off the life time of a task, and that is our internal SwitchOut API. All it essentially does is set some state and notify the runtime of the switch out:
HRESULT hr = m_pCallback->SwitchOut();
Next time we’ll go over the remaining APIs on IHostTask that we haven’t covered yet.
Last time we successfully created a task and started it running. That’s an accomplishment, but there are a couple of details we should get out of the way before we start to dive deeper into the fiber mode implementation. Those are all on IHostTask and are Alert and Join. Once again everything else is trivial or non-important for CoopFiber’s implementation.
Last time we saw a peek at Alert. This was the m_hCurThread member variable that we set when a fiber was switched in. Our Alert implementation uses this:
QueueUserAPC(&MyAPCProc, m_hCurThread, NULL);
Here we check if the current task is running, and if so we queue an APC to that task. The queued APC is just a simple do-nothing function to wake the task out of its blocking operation. Whether the task is running or not we set the alert bit.
One interesting aspect of this simple sample is that if the user doesn’t schedule the task the alert can never respond. A more complex host may choose to give priority to alerted tasks or schedule them immediately.
The next API to look at is the Join implementation:
HRESULT __stdcall CHostTask::Join(DWORD dwMilliseconds, DWORD option)
if(option & WAIT_ALERTABLE)
result = WaitForSingleObjectEx(m_hTaskExitedEvent, dwMilliseconds, true);
result = WaitForSingleObject(m_hTaskExitedEvent, dwMilliseconds);
_ASSERTE(!"Shouldn't reach here");
Here we simply block the current task on an event that is set in our internal CHostTask::ExitTask API. We’ll do an alertable wait if requested, to which the APC queued in Alert will wake us up. Finally Join translates the result of WaitForSingleObject* into the appropriate host HRESULT.
We’ve mentioned ExitTask twice now (once in SwitchIn and here again) so now seems like an appropriate time to cover it. This internal API merely calls the ICLRTask::ExitTask callback, notifying the runtime the task has exited, and updates our internal bookkeeping:
The one interesting call worth noting here is that we set the event that allows our Joined tasks to wake up. A more complicated host would use Join as an opportunity to deschedule a fiber and would need a more sophisticated mechanism of handling exited tasks.
Well that wraps it up for this edition… There’s only one more piece of unmanaged code before we start getting into the managed world. Next time we’ll delve into the synchronization primitives.
The synchronization primitives are handled off to the runtime by the IHostSyncManager interface. We’ve already provided this to the runtime through our GetHostManager callback on IHostControl. Our IHostSyncManager is implemented on our IHostTaskManager and for the most part we just create objects and hand them off. For example CreateCrst looks like:
*ppCrst = (IHostCrst *)new CHostCriticalSection(this);
if(NULL == *ppCrst)
And none of them are very different. Our SetCLRSyncManager does nothing. A more sophisticated host could use the ICLRSyncManager to help perform deadlock detection.
The CoopFiber implements 4 synchronization primitivies: Auto Events, Manual Events, Critical Sections, and a Semaphore. All of these with the exception of the critical section are just thin wrappers over the equivalent OS API. For example looking at CHostManualEvent::Wait:
if(option & WAIT_ALERTABLE)
result = WaitForSingleObjectEx(m_hEvent, dwMilliseconds, true);
result = WaitForSingleObject(m_hEvent, dwMilliseconds);
_ASSERTE(!"Shouldn't reach here");
We can see an implementation that is nearly identical to Join we saw last time. Both the auto event and semaphore implementations are nearly identical. More sophisticated hosts could perform deadlock detection below these events (for reader/writer locks and monitors built on top of the events), or they could choose to schedule other fibers on these threads. For this simple implementation we simply block the current thread.
The critical section is the only synchronization primitive which doesn’t simply wrap the OS API. This is because the critical section is owned by a specific thread (unlike the events and semaphore). Because of this the critical section must be aware of the fibers in addition to threads. This will prevent one fiber from acquiring the critical section, and having another fiber re-acquire on the same thread.
The essence of the critical section acquire lives in TryEnter, which Enter builds on:
if(m_holderTask == NULL)
// no one holds the critical section
if(m_holderTask == NULL && WaitForSingleObject(m_hEvent, 0) == WAIT_OBJECT_0)
// we've acquired the crit section
m_holderTask = curTask;
m_dwEnterCount = 1;
*pbSucceeded = TRUE;
else if(m_holderTask == curTask)
// we already hold the critical section
if(m_holderTask == curTask)
*pbSucceeded = TRUE;
There’s a couple of points to note. First, we use a critical section to protect our state. We don’t want to worry about other threads entering. Also we use an event to block the task if the critical section cannot be acquired. A more sophisticated fiber scheduler would want to re-schedule another fiber rather than block the current thread.
Those are the core synchronization primitives that we’re using in CoopFiber. You can see by limiting the scope of what CoopFiber does we were able to merely rely upon the OS APIs in most circumstances. Next time I’ll start discussing the managed / unmanaged fiber API interface.
At this point we’ve covered nearly all the major components of the unmanaged host. The one remaining detail is the interface that’s used between the managed fiber mode implementation and the unmanaged host. This is all implemented in callbacks.cpp. We essentially expose an API for all the major operations we allow the fiber API to do. These include creating fibers, switching fibers in, aborting fibers, and exiting the current fiber.
The creation of a fiber differs from the CreateTask API we covered before in that we aren’t creating a new thread for this fiber. This fiber is newly created and won’t run until a user switches it in. Aborting fibers is exactly like aborting a thread, but a fiber will need to be switched in to be properly aborted.
Switching in fibers is interesting. Here you’ll find no “SwitchOut” API like the internal unmanaged SwitchOut method on CHostTask. This is because we cannot run managed code on a “switched out” task. It has to have some task to run on! Instead CoopFiber exposes one API for switching in a new task that also switches out the current task.
All of these methods are merely thin wrappers over the functionality we’ve already covered. Two interesting examples of the several functions include InternalCreateFiber and InternalSwitchIn.
First let’s look at InternalCreateFiber:
__declspec(dllexport) PVOID InternalCreateFiber(PVOID startAddr)
CHostTask *tmp = CHostTask::CreateTask();
if (tmp == NULL)
_ASSERTE(FALSE && "Out of memory in CreateTask!");
This function creates a new CHostTask, sets the start address (which is a delegate passed from managed code), and create a new fiber for the task. We return the task back to managed code which now holds the only reference to it.
The interesting thing to note is the management of the lifetime of the CHostTask. We have 1 reference to it from the managed code. As we’ll see later the managed code uses a new Whidbey feature called SafeHandle. This ensures that when the managed Fiber object is collected our InternalReleaseFiber method will be called.
Next let’s look at InternalSwitchIn:
__declspec(dllexport) void InternalSwitchIn(CHostTask *task)
CHostTask *curTask = CHostTask::GetCurrentTask();
_ASSERTE(curTask && task);
Here we get the current task, switch it out, and switch in the task passed in. Again, we have another simple thin wrapper over the APIs we’ve already seen. All of the other callbacks are thin wrapper as well.
So we’ve now covered nearly all the main principals of the unmanaged code. Soon we can start to discuss what the host is going to expose to the managed code author!
It seems like a good time to take a breather and look at what we have going on so far.
First, we’ve started the runtime. We’ve handed our IHostControl off to the runtime. The runtime has called back to our IHostControl and gotten a couple of managers. Those are our task manager and our synchronization manager. Whenever the runtime needs to create a thread it’s called us back, and we’ve created a brand new thread. Sure, we’ve converted it into fibers, but we’ve done no real fiber switching.
Whenever the runtime needed a manual or auto event we’ve given it to it via the synchronization APIs. When it needed to block on it, it called us, and we blocked on it via IHostAutoEvent or IHostManualEvent. If another thread alerted the thread blocked on the event, the runtime called us via the IHostTask APIs, and we queued and APC to it.
If the runtime needed to enter a critical section, it called us, and we blocked or allowed it to enter via the IHostCrst APIs.
We’ve set up everything necessary to replace the CLR’s threading model, but for the most part we’ve merely delegated to the OS APIs. Sure, there were minor differences here and there… But for every task the CLR asks for we create 1 physical thread. And sure every one of those physical threads has already been converted to a fiber, but we never switch those fibers out.
Starting with the next article that’ll start to change.
The managed Fiber class exists in its own directory in the SDK sample appropriately called Fiber. The Fiber class is designed to be vaguely similar to the managed Thread class. For example, like the Thread has ThreadState the fiber has FiberStates.
The managed fiber class exposes a few significant APIs:
· public static Fiber CreateFiber(FiberStart fs)
· public static Fiber CurrentFiber
· public void SwitchTo()
· public void Abort()
· public void RudeAbort()
· public void Exit()
· public FiberStates FiberState
The CreateFiber API should be obvious. It takes a FiberStart delegate and passes it into the unmanaged InternalCreateFiber API we previously looked at.
CurrentFiber is nearly just as obvious: We store the current fiber in managed thread local storage (or in our case it’s really fiber local storage) so we can easily fetch it. If we haven’t created a managed Fiber object for this fiber yet we’ll get it from the host via a P/Invoke into the InternalGetCurrentFiber API. This simply gets the currently executing CHostTask, AddRef’s it, and returns it. The managed half simply sticks this into our SafeHandle to ensure it’s properly cleaned up.
The last trivial method here is FiberState. This just returns m_FiberStates which the managed Fiber class maintains as the fibers switch through various states.
The interesting APIs here though are actually SwitchTo, Abort, and RudeAbort. We’ll start at looking at SwitchTo.
The first thing we watch out for in the managed implementation is that we don’t try and switch a fiber in on 2 threads:
Fiber curFiber = CurrentFiber;
if ((m_FiberStates & (FiberStates.Running|FiberStates.Switching)) != 0)
throw new FiberStateException("Attempt to switch to a fiber that is running or already switching!");
m_FiberStates &= (~FiberStates.Unstarted);
m_FiberStates |= FiberStates.Running;
If the fiber was already running, or is currently involved in a switch, then we’ll throw an exception that you cannot currently switch. We’ll then update the fiber we’re trying to switch in so it’s now officially running (this will prevent anyone else from switching it in).
Next we need to make sure that no one races in and tries switching in the fiber we’re switching away from.
m_FiberStates |= FiberStates.Switching;
// we''ve marked us as switching, do one last check to see if someone wanted to abort us.
// Anyone after this will get us aborted on our next switch in.
So we update its state to mark that it’s currently switching out. You’ll also notice we’re checking to see if we need to abort a thread. We’ll cover this more in-depth in the next article where I discuss the Abort & RudeAbort implementation.
m_prevFiber = curFiber;
// switch in the fiber the user requested
Next we mark what the previous fiber was (we’ll need to update it to remove the Running & Switching bits), and then call back into the unmanaged host to perform the actual switch. This goes into the API that we looked at in Article 7 – we simply switch out the current task, and switch in the new one that we passed in.
Finally we call OnFiberSwitchIn. Again this is another place where we have both a top-half before the switch, and a bottom-half after we’ve switched away and switched back. When we do the switch in if it’s the 1st time a task has been scheduled we’ll end up back at RealFiberStart. If this task has already switched out once, we’ll end up at the curFiber.OnFiberSwitchIn line, but we’ll be on a different fiber (we’ll be on curFiber). In either case we’ll set the state on the previous fiber so that it’ll be schedulable again, and we’ll check the newly switched in fiber to see if it should be aborted.
And that’s how we switch fibers. You first create a fiber, and then you call SwitchTo on the newly created fiber. We largely just do some book keeping, and then call directly into the host to do the switch. It’s that simple.
That takes us through nearly all the basic mechanisms of the fiber mode host. In the next article I’m going to discuss how the Fiber class exposes Abort and RudeAbort APIs. A typical host wouldn’t expose these to managed code, but the CoopFiber sample has it’s reasons for doing so…
In this article we’re going to look at the implementation of Abort and RudeAbort. In the last article I mentioned that a typical host wouldn’t need to expose these to managed code. Why is that? If you have a fiber mode scheduler typically Thread.Abort will be sufficient. Your scheduler will eventually schedule the task, and the task will then be aborted.
But in the CoopFiber sample we don’t have a scheduler. Therefore a user could call Thread.Abort on a switched out fiber, and it would never get scheduled to be aborted. What’s worse is that the call into ICLRTask::Abort will block until the thread gets scheduled again.
To handle this peculiarity when an Abort request comes in the Fiber class first determines whether the task is running or not. If it is already running then we’ll go ahead and abort it right away. Otherwise we’ll set a bit to notify that on the next switch we should abort the task. Here’s the Fiber.Abort implementation:
bool fAbortNeeded = false;
m_FiberStates |= FiberStates.AbortRequested;
if ((m_FiberStates & FiberStates.Running) != 0 && (m_FiberStates & FiberStates.Switching) == 0)
//the current fiber is aborted, so we can initiate the abort now.
fAbortNeeded = true;
InternalAbort will just turn around and call ICLRTask::Abort on our already switched in task. In our last article we saw our calls to CheckForAbort during task switch in. That code simply looks like:
// Next see if the user requested an abort on this thread.
if ((m_FiberStates & FiberStates.AbortRequested) != 0)
else if ((m_FiberStates & FiberStates.RudeAbortRequested) != 0)
We simply call back to Abort or RudeAbort, which will then call into InternalAbort to finally Abort/RudeAbort the task. The task is now switched in and running so we’ll call into the host to perform the actual abort (which now won’t block because the task is running).
At this point you may be asking yourself “What is this Rude Abort thing?” Rude aborts are actually a new Whidbey feature, and can be accessed one of several ways. The only difference between a rude abort and a normal thread abort is that the rude abort will not execute your catch/finally blocks. In addition to being exposed directly through the hosting APIs rude abort’s can also occur due to escalation policy (also configured via the hosting APIs). That’ll have to be saved for another blog entry…
CoopFiber’s Rude Abort implementation is essentially identical to the Abort implementation. The only difference is that we’ve replaced the work Abort with RudeAbort everywhere.
So that’s it for the Abort/Rude Abort implementation. We’ve almost reached the end of this serious, but there’s one last API that’s worth covering on the managed size: Fiber.Exit. I’ll go over that implementation next article.
Last week we went over the Abort and RudeAbort APIs. This week we’ll go over Fiber.Exit. This API provides a way for you to terminate a running fiber, and demonstrates a use of the unmanaged ICLRTask::ExitTask API. The ExitTask API can only be called on a fiber that is currently switched in which gives us a similar problem to what we had in Abort/RudeAbort. But because the ExitTask call will not block for a long period of time we handle it a little differently than Abort and RudeAbort.
After checking & updating our state like we did in Abort and RudeAbort, the ExitTask API does:
if (this == Fiber.CurrentFiber)
// exiting a running task is easy
// only tasks that are running can call ICLRTask::ExitTask.
// We need to switch the task in, call ExitTask, and then
// switch back to our current fiber.
Here you can see we take one of two actions. Either we call InternalExitTaskAndTherad() which will cause both the current thread and fiber to exit, or we call into InternalExitTaskAndSwitch.
The first call is pretty self-explanatory. We’re the current thread, we want to let the whole thing die off – this is exactly the same to calling DeleteFiber on the currently running thread.
The second call is a little different. Here we have a fiber that is currently switched out. We want to re-schedule the fiber we’re asking to exit, call ExitTask on it, and then switch back to our previously running fiber. Here we go back to the code in SwitchIn that we looked at in article 4:
The task has been requested to exit, we call ICLRTask::Exit on it, and then we switch back to the previously running task having completed the work the user requested.
One note worthy point here is that like the DeleteFiber APIs, the ExitTask API is potentially unsafe. This is because we’re exiting the thread with code higher us still on the stack. This code may have resources to free or other state to clean up. Typically a host would only call ExitTask after all managed code has left the stack.
That brings us to the end of the CoopFiber series. We’ve gone over the smallest set of APIs that are required for implementing fiber mode. We’ve then exposed the APIs to the managed code author to allow them to be in control of the scheduling. To implement a scheduler on top of this would require updating the synchronization primitives so they’d select new tasks and switch them in instead of blocking the thread. And hopefully you’ve walked away from all of this with a better understanding of the interactions between the CLR and the host when running in fiber mode.