CLR Add-In Team Blog : Behind the Scenes

Add-In Lifetime Management [Pete Sheill, Jim Miller]

CLR Add-In Team — Wed, 18 Jul 2007 02:03:00 GMT

A good question to ask when evaluating a design is ‘how is the lifetime of this object or component managed?’ That is,

· How do you know it isn’t needed anymore?

· Is it possible to release the resources while the object is still in use?

· Is it possible to “leak” the resources by not releasing them at all?

· How soon after the object isn’t needed are the resources released?

How does this apply to the managed add-in model? If you are content to keep the add-in loaded until the process exits (and the system cleans up the entire process) you can stop reading right away, as this topic isn’t of particular interest to you.

One of the greatest benefits of managed code, of course, is automatic lifetime management (garbage collection). Within an application domain (“appdomain”) objects no longer referenced by “live” objects are automatically reclaimed by the garbage collector and there’s a standard mechanism (finalization and IDisposable) to release any unmanaged resources those objects are using.

The resources to be reclaimed include the memory for the instance members, any operating system handles, database connections, etc. Another resource, often overlooked in managed code, is the memory taken by the code itself, including the JIT-compiled code. Releasing this last resource is not possible if the code is loaded in the same appdomain as the host. We simply don’t have a way to unload an assembly without unloading the appdomain that hosts it.

In general, there are three ways to manage the lifetime of objects:

1. Garbage collection. This works within a single appdomain as described above. Unfortunately, there’s no good general purpose solution for use in distributed systems (although it’s been an active research area for years).

2. Reference counting. This is probably familiar to you from COM and other systems. When you create an object you set a variable to 1, whenever you add a new reference to it you increment the variable (“addref”), when you release a reference you decrement the variable (“release”). When the variable goes to 0 there are no more references and you can release the object and any data it holds. This works as long as there are no cycles between objects, but leads to memory leaks when a cycle occurs.

3. Sponsorship. This is the mechanism used for both DCOM and .NET Remoting. The idea is that when you create a remote object you declare something as a “sponsor” for the object and periodically ask the sponsor if the object is still needed. If the sponsor says it isn’t needed, or if you can’t reach the sponsor after some number of tries, you can release the object. One common way of implementing sponsorship is what’s called the “lease” model where the sponsor provides a lease that states how long the object should be considered alive and the sponsor isn’t contacted until the lease expires.

The managed add-in framework uses a combination of all three of these mechanisms. Within a single appdomain it uses garbage collection. But it gets a lot more interesting when the add-in is being run in a separate appdomain in the same host process, or in a separate process. Even though the HostSideAdapter has a reference to the AddInSideAdapter, because the AddInSideAdapter is “remote” it is subject to reclaiming under normal garbage collection.

In designing the lifetime management system for managed add-ins, our goal was to make simple cases simple but still allow more complicated systems to be built. The framework itself takes responsibility for the sponsorship model, but exposes a reference counting model to control the behavior of the sponsor. In simple cases the reference count is maintained automatically by the framework, too, using the garbage collector and finalization. The rest of this article talks about the details of this implementation.

In the case where the add-in is isolated from the host, either in a different appdomain or a different process, the garbage collector still reclaims objects when they are no longer referenced. If you release the reference to the HostSideAdapter the garbage collector will release its memory. But what about the corresponding AddInSideAdapter and the add-in itself? And what about the case where you allowed the add-in framework to create an appdomain for running the add-in – when is the appdomain released?

The standard solution to the issue of keeping the AddInSideAdapter alive in .Net Remoting is to use leases and sponsorship to keep the remote object alive. While we do use sponsorship underneath, we decided not to expose this to the add-in or pipeline developers. Instead, we use a variant of the “ref counting” technique to keep remote objects alive by providing the methods AcquireLifetimeToken() and RevokeLifetimeToken(). When the HostSideAdapter is constructed, it immediately makes a call to AcquireLifetimeToken() on the AddInSideAdapter to tell the AddInSideAdapter that it has a reference to it. When the HostSideAdapter is disposed of or reclaimed, it will make a call to RevokeLifetimeToken() on the AddInSideAdapter to let it know that it is done referring to it. Usually, this will lead to the AddInSideAdapter and the add-in being reclaimed.

Let’s consider a simple scenario first – an add-in in its own appdomain in the host process. Say you have activated an add-in using the overload of Activate() that takes an AddInSecurityLevel. This method creates a new appdomain to host the add-in. As described in the post on activation, the HostSideAdapter calls AcquireLifetimeToken() on the AddInSideAdapter when it is created. This increments the “ref count” on the AddInSideAdapter to one. As a convenience, this is usually done by constructing and holding a ContractHandle, passing in the AddInSideAdapter to the constructor -- the constructor of the ContractHandle actually calls AcquireLifetimeToken. We’ll assume that this is the case for this example. As long as this ref count is above zero, the AddInSideAdapter will stay alive in memory. Since it has a reference to the add-in, the add-in will therefore also stay alive in memory.

The host uses the add-in through the HostViewOfAddIn (previously called HostAddInView), and then decides that it no longer needs it. The variable that used to reference it is set to null. At some later point, when the garbage collector runs, it notices that the HostViewOfAddIn is no longer needed, and therefore neither is the ContractHandle. It calls the finalize method of the ContractHandle, which then calls RevokeLifetimeToken() on the AddInSideAdapter. The AddInSideAdapter decrements the ref count to zero. This triggers cleanup – the add-in is no longer needed. If the AddInSideAdapter has been implemented by deriving from the framework class called ContractBase (highly recommended), then the following happens:

1) A flag is set to end the sponsorship (in remoting) that is keeping the object alive.

2) OnFinalRevoke() is called, allowing the derived class to clean up any native resources it holds. We chose to name the method this way instead of calling it Dispose() because Dispose() is a public method typically called by an external object, while this method is a protected method called by the object itself.

3) We unload the appdomain with a call to AppDomain.Unload(). Before unloading completes, the finalizers of all the objects in the appdomain will run.

So in this example, the cleanup happened without any explicit instruction to do so by the host or the add-in, similar to normal single-appdomain garbage collection.

The nice part about this approach is that the host code is isolated from the lifetime management of the add-in. It just uses the HostViewOfAddIn as it would any other managed object, without doing any reference counting itself – because that code is only done in the adapter. When there are no more live references to the HostViewOfAddIn, all the memory and resources of the adapters and add-in will automatically be reclaimed.

There are times where steps #1 and #2 will happen, but not #3. That is, the add-in is ready for cleanup, but the appdomain is not. If the appdomain was not created during activation of this add-in, then the AppDoamin will not be unloaded here. The appdomain may be the default host appdomain, it may have been explicitly created by the host, or it may have been created for another add-in. In any case, there are other objects in the appdomain that are likely still in use, so we can’t unload it. Stated another way, if we didn’t create the appdomain, then we won’t unload it.

Assuming that the appdomain was created specifically for the add-in, there is another situation that will postpone the cleanup. Reference counting relies on an object "owning" its own memory and other resources. That is, the object itself is responsible for deallocating the resources at the right time, once it is sure that no other object needs it. The appdomain created for the add-in will typically have the same lifetime as the add-in. While we could have kept a separate ref count for the appdomain, having the appdomain own itself, we decided to simplify things and have the primary add-in own the appdomain. Therefore the two always have the exact same lifetime. Only when the ref count of the add-in goes to zero does the appdomain get unloaded, causing any objects in that appdomain to be finalized and unavailable.

One question that might arise is what happens if the add-in creates an object and passes a reference to it to the host, and then goes out of scope before the host uses the object. A separate pipeline is created for the object as it is passed to the host, similar to the pipeline between the host and the add-in. If the add-in's reference count went to zero, the add-in and the appdomain would be reclaimed. But then if the host still held a reference to the object and tried to call one of its methods, it would fail with an AppDomainUnloadedException.

To address this, we don't allow the add-in's reference count to go to zero in this situation until the host no longer references the object. When the object is passed to the host and a pipeline is created for it, we look up the owner of the appdomain and increment its ref count. Then when the object is no longer needed and the pipeline is being finalized we decrement its ref count. Only at this point can the ref count of the primary add-in go to zero, leading to the cleanup of the appdomain.

If the host calls Activate to create a new appdomain for a new add-in, then uses that same appdomain in subsequent calls to activate secondary add-ins, a similar process happens. The secondary add-ins increment the ref count of the primary add-in, so that the appdomain won't be cleaned up while they are still in use. The secondary add-ins decrement the primary add-in's ref count when they are no longer referenced, permitting appdomain cleanup to proceed.

Note that this version of reference counting improves on some other versions in that you can’t accidentally remove a reference that a different object created. That’s because AcquireLifetimeToken() returns a unique “token” number that should be stored and passed back to RevokeLifetimeToken(). Revoking a token that you didn’t previously acquire will by and large have no effect, aside from causing an InvalidOperationException to be thrown.

There’s more to say about lifetime management, but we’ll leave that for later posts. It’s a multifaceted issue, but we hope that most hosts and addins will be able to be written as if all the resource cleanup is governed by garbage collection, even though there is a bit more to it than that underneath.

Behind the Scenes: Activation [Pete Sheill]

CLR Add-In Team — Thu, 28 Jun 2007 18:42:00 GMT

Let’s discuss the specifics of the construction of the add-in, the isolation boundary and the pipeline in the add-in model – i.e. activation. I’ll be referring to the discovery and activation as discussed here and the segments of the add-in pipeline as discussed here . Let’s say you have discovered a single token for an add-in, and you have decided to activate it. To isolate the add-in from the host you chose to run it in its own new appdomain. What happens next when you call one of the Activate() methods on the add-in token? Let’s enumerate all of the steps that the system takes:

1. The appdomain is created with the permissions that you specified in the call to Activate().

2. The add-in assembly is loaded into that appdomain through a call to Assembly.LoadFrom(), passing in the location of the assembly. The add-in type will not be loaded in the host’s appdomain. In other uses this call can cause loader context issues if not used carefully, but we’ve taken steps to avoid them here. In fact, this method was created specifically to support add-in scenarios.

3. We use reflection to call the no-argument constructor for the add-in to create an instance in that appdomain. Naturally, since the add-in derives from the AddInBase class that is deployed in the AddInView assembly, this action causes the loader to load that assembly. At this point we have an instance of the add-in running in its own appdomain. Now we need to connect it to the host.

4. An instance of the AddInSideAdapter is constructed, passing in the add-in (typed as the add-in base) as the only argument to the constructor. (This adapter implements a Contract interface and derives from MarshalByRefObject through the intermediate ContractBase class. Therefore it can appear to live in both the host’s and the add-in’s appdomain—any calls to it from the host’s domain are proxied and executed in the add-in’s appdomain.)

5. The activation code passes the add-in adapter back to the host’s appdomain typed as the Contract that it implements.

6. An instance of the HostSideAdapter is constructed in the host’s appdomain, with the AddInSideAdapter being passed in as its only argument. The exact HostSideAdapter type is determined by examining the add-in token. This adapter derives from (or implements) the HostViewOfAddin that the host compiled against.

7. The activation code returns the host-side adapter to the host, typed as the HostViewOfAddin.

The host will sometimes do further initialization of the add-in through a separate call, passing in any needed arguments. Then it is up to the host and add-in to communicate as needed. Activation has completed.

Do the adapters need to be public? Actually, no. Though the normal rules of visibility would suggest that they would need to be public in order to be created and used by the activation code, the rules don’t apply in this case. That’s because we use reflection to invoke the constructor, and given enough permission, reflection can invoke non-public constructors. We didn’t want the adapters to need to be public because they exist as an implementation detail, not things to be documented and supported in themselves.

When the HostSideAdapter is constructed with a reference to the AddInSideAdapter, it does something right away that we wouldn’t need to do if all the objects were in the same appdomain. It needs to call the AcquireLifetimeToken() member, specified in the IContract interface, of that adapter. That is part of another big topic, lifetime management. We’ll discuss that in another post.

This is one way to activate an addin in this model. There are also some other different ways you could activate the same addin. You could choose to activate it in the same appdomain as the host. You could also choose to activate it in an entirely separate process, if isolation matters above all else. We’ll explore those options more in later posts.

Behind the Scenes of Add-In Discovery in the Orcas System.AddIn [Jesse Kaplan]

CLR Add-In Team — Fri, 09 Feb 2007 00:19:00 GMT

Details about the System.AddIn’s Implementation of Add-In Discovery

Last time we discussed several common approaches to add-in discovery and some of the pros and cons of each. We reviewed type hierarchy, custom attribute, and xml manifest based discovery systems and primarily evaluated them on three high level criteria: development complexity, performance, and add-in developer experience. This time I’d like to go into the details on what we developed and how it builds on the lessons we learned while evaluating previous solutions.

Implementation Overview

We had two high level goals in mind when we developed our discovery system: minimize complexity for the add-in developer and make the solution fast enough to be used at runtime. We wanted the add-in developer experience to be as close to “inherit from an abstract base class and run with it” as possible and we wanted hosts to be able to use the UI thread to discover add-ins.

Fundamentally the system we developed is mostly based on the custom attribute approach but with intelligent caching and updating that lets you avoid doing the work at runtime. We tried to capture the add-in developer experience of the custom attribute solutions with the performance of the manifest based approach.

At development time the add-in developers experience is as simple as with the custom attribute model: they inherit from the right abstract base class, apply the AddInAttribute, and then start writing the add-in.

As we noted earlier however, the custom attribute based approaches have the downside that computing this information requires loading and examining a bunch of assemblies and are too slow to do on application start up or on the UI thread. With this in mind we went a step further and built a system that caches this information to disk. This also led us to split our discovery into two phases: Update and Find.

AddInStore.Update(addinPath);

IList<AddInToken> tokens =

AddInStore.FindAddIns(typeof(AddInType), addinPath);

Update Details

The update phase is where we do the work to examine the add-in directory and build the store (or cache) of all the add-ins available there. For each sub directory at the provided path we look at each dll in the directory looking for a type that has [AddInAttribute] applied to it and record the information in the attribute and the base class of the add-in and store all the found information in a file called AddIns.store in the directory provided. One thing to note here is that we examine all of these assemblies in a different AppDomain and we use ReflectionOnly loading: this ensures that the add-in code is never executed until it is activated and that a call to update does not pollute the hosts AppDomain with these assemblies. Rather than recomputing all this information at each call to update we examine the timestamps of the various items in this directory and compare it to the existing store file (if there is one) and decide whether or not there is anything new we need to look at and if not we return quickly.

In addition to providing an update method that does this work we also ship the command tool AddInUtil.exe with the framework that was designed to be called with a custom action in an installer or via a build script.

By providing both a runtime Update method and the command line tool we leave an important decision up to the host: the host can choose to call AddInStore.Update from within the host app and thus make the add-in deployment experience truly an x-copy one, or it can require that add-ins run the tool themselves as part of their setup. In addition we’ve also ensured that the store file itself is x-copyable along with the add-in directory and so if, for example, a host ships with a few add-ins pre-installed it can build the store file when it’s building its setup and just deploy that store file along with the add-ins.

FindAddIns Details

In FindAddIns the host passes us the type it wants to use to talk to the add-ins, the directory it wants us to look in and it receives back a collection of AddInTokens representing all the add-ins we found that can be used through the provided abstract base class. This method was designed to be usable during application startup and on the UI thread and we go out of our way to make sure that no types are ever loaded during this call and that the only files we read are the store files at the specified location. If no one (either the host or the add-in) performed an update on that location then no add-ins will be found. Another interesting thing we do is that we keep the store file in memory so that subsequent calls to FindAddIns on the same directory will not require us loading the file again: we simply check to see if the file has been updated since we last loaded it from disk and only reload it if necessary.

The AddInToken objects returned from a FindAddIns call are the objects that the host can actually activate to get back an instance of the add-in. They also contain metadata about the add-in that the host can use to decide which add-ins it wants to load: the add-in always provides a friendly name for itself and can optionally specify a version, publisher, and a short description. All of this information was originally recorded by examining, but not loading, activating, or executing, the add-in during the Update call and was stored in the token object during FindAddIns: this means that the host can get specific information about the add-ins and make informed decisions about which ones to activate without having to every execute any add-in code.

Putting it Together

Let’s start with reviewing our three high level goals:

· Minimize complexity of the add-in developer

· Performance of discovery code at runtime

· Ease of host development

Fundamentally all an add-in developer has to do with our system is to inherit from the right abstract base class, apply the [AddInAttribute] to the add-in, and then copy the add-in to the directory the host looks. This was our pri-1 requirement and we’ve made sure that it’s just about as low overhead on the add-in developer as possible.

As far as performance is concerned we leave it up to the host to decide what is most important: can it handle the cost of updating the stores at runtime when new add-ins are installed and reduce the complexity of add-in deployment, or is it acceptable to require a custom action in the installer. If the add-in deployment is responsible for updating the store then our solution is faster than the xml based discovery – since we only need to look at one file and we don’t have to load an xml parser to do so – and if the host decides to do runtime Update then it only pays the cost of discovery when new things are installed and we handle caching that information to disk for future look ups.

Finally we come to the ease of host development and here we may have the best story of all: while our solution may be harder to develop than the solutions we reviewed last time, we’ve removed this complexity since will be shipping as part of the framework.

We really do let you install and find add-ins in two lines of code:

AddInStore.Update(addinPath);

IList<AddInToken> tokens =

AddInStore.FindAddIns(typeof(AddInType), addinPath);

At the beginning of the last article I mentioned some exotic discovery mechanisms such as in a database, embedded in a document, and over RSS. We’re actually working with partners who are building these mechanisms on top of our discovery system and down the line we’ll have a series of blog posts demonstrating some of these techniques.

In our next behind the scenes post we’ll pull back the curtains on the magical third line of code that activates your add-ins:

token.Activate<AddInType>(AddInSecurityLevel.Internet)