Lifetime Leases
Marshal-by-reference objects (MBRs) do not reside in memory forever, whether server-activated Singleton objects or client-activated objects. Instead, unless the type overrides MarshalByRefObject.InitializeLifetimeService to control its own lifetime policies, each MBR has a lifetime that is controlled by a combination of leases, a lease manager, and some number of sponsors. (In this case, an MBR object's lifetime ** is the total time the object remains active in memory.) A lease is the period of time that a particular object will be active in memory before the .NET remoting system begins the process of deleting it and reclaiming the memory. The server application domain's lease manager is the object that determines when the remote object is marked for garbage collection. A sponsor is an object that can request a new a lease for a particular object by registering itself with the lease manager.
Whenever an MBR object is remoted outside an application domain, a lifetime lease is created for that object. Each application domain contains a lease manager that is responsible for administering leases in its domain. The lease manager periodically examines all leases for expired lease times. If a lease has expired, the lease manager walks its list of sponsors for that object and queries whether any of them want to renew the lease. If no sponsor renews the lease, the lease manager removes the lease, the object is deleted, and its memory is reclaimed by garbage collection. An object's lifetime, then, can be much longer than its lifetime lease, if renewed more than once by a sponsor or by continually being called by clients.
Because the remote object's life is independent of the lives of its clients, the lease for a simple or lightweight object can be very long, be used by a number of clients, and be periodically renewed by an administrator or a client. This approach uses leases efficiently because very little network traffic is needed for distributed garbage collection. However, remote objects that use scarce resources can have a lease with a short lifetime, which a client frequently renews with a short time span. When all the clients are finished with the remote object, the .NET remoting system deletes the object quickly. This policy substitutes increased network traffic for more efficient use of server resources.
Using leases to manage the lifetime of remote objects is an alternative approach to reference counting, which can be complex and inefficient over unreliable network connections. Although leases can be configured to extend the lifetime of a remote object longer than is precisely required, the reduction in network traffic devoted to reference counting and pinging clients makes leasing an attractive solution when properly configured for a particular scenario.
The following table describes the have five main properties of leases.
| Property | Description |
|---|---|
| InitialLeaseTime | Specifies the initial span of time that an object will remain in memory before the lease manager begins the process of deleting the object. In the configuration file, this is the leaseTime attribute of the <lifetime> configuration element. The default is 5 minutes. A lease time of zero sets the lease to an infinite lifetime. |
| CurrentLeaseTime | Specifies the span of time left before the lease expires. When a lease is renewed, its CurrentLeaseTime is set to the maximum of the CurrentLeaseTime or the RenewOnCallTime. |
| RenewOnCallTime | Specifies the maximum time span that the CurrentLeaseTime is set to after each remote call to the object. The default is 2 minutes. |
| SponsorshipTimeout | Specifies the time that the lease manager waits for the sponsor to respond when notified that a lease has expired. If the sponsor does not respond in the specified time, the sponsor is removed and another sponsor is called. If there are no more sponsors, the lease expires and the garbage collector disposes of the remote object. If the value is "0" (TimeSpan.Zero), the lease will not register sponsors. The default is 2 minutes. |
| LeaseManagerPollTime | Specifies the amount of time that the lease manager sleeps after checking for expired leases. The default is 10 seconds. |
Leases are created when an MBR object is activated in another application domain. At that point, when the ILease.CurrentState property is LeaseState.Initial, the lease properties can be set. Once set, they cannot be changed directly. Only the CurrentLeaseTime can be changed, either from an ILease.Renew call or when the lease manager calls ISponsor.Renewal on a sponsor and the sponsor responds with a TimeSpan object. MarshalByRefObject has the default implementation of a lifetime lease, and unless this lease is modified when it is created, the lease properties are always the same.
Modifying Lease Properties
The lifetime lease properties can be modified in two ways:
- Declaring custom lifetime lease properties by overriding MarshalByRefObject.InitializeLifetimeService in your MBR object, either to set the properties on the lease yourself or to return a null reference (Nothing in Visual Basic). The latter option tells the .NET remoting system that instances of this type are intended to have an infinite lifetime.
- You or an administrator can also specify lifetime properties for all objects in a particular application in the <lifetime> element in the application or machine configuration file. For details, see Initializing Leases.
Once created, a lease can be renewed in three ways:
- A client calls the ILease.Renew method directly.
- If the ILease.RenewOnCallTime property is set, each call to the remote object renews the lease for the specified time.
- The lease calls an ISponsor.Renewal method requesting a lease renewal and the sponsor responds with a TimeSpan.
For details, see Renewing Leases.
Lease Managers
Lease managers must periodically examine leases for time expiration. When a lease's time has expired, the lease is informed and it attempts to renew itself by invoking its sponsors.
The lease manager also maintains a list of sponsors from which leases are waiting for replies. If a sponsor does not respond in the interval specified by the SponsorshipTimeOut time span, it is removed from the sponsor list.
When a lease is allowed to expire, no further lease messages or sponsor returns are accepted. The lease's reference is removed from the lease list, and the .NET remoting system removes the object reference from its internal table. The garbage collection system then removes the lease and the object.
See Also
Object Activation and Lifetimes | Remoting Example: Lifetimes | Remoting Settings Schema | ILease | RemotingServices.GetLifetimeService | MarshalByRefObject.InitializeLifetimeService | Initializing Leases | Renewing Leases