Lifetime Leases

This topic is specific to a legacy technology that is retained for backward compatibility with existing applications and is not recommended for new development. Distributed applications should now be developed using the Windows Communication Foundation (WCF).

Marshal-by-reference objects (MBRs) do not reside in memory forever, whether they are 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 a 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 is active in memory before the .NET Framework 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 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 sends a request to its list of sponsors for that object and queries whether any of them commit 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.

A remote object's life is independent of the lives of its clients. The lease for a basic object may be very long, in which case the object may be used by multiple clients. The object's lease may be periodically renewed by a client, keeping the object alive longer. This approach uses leases efficiently because very little network traffic is required 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 Framework remoting system marks the object for garbage collection 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 sending requests to clients, makes leasing an attractive solution when properly configured for a particular scenario.

The following table describes the main properties of leases.

Property Description

InitialLeaseTime

Specifies the initial span of time that an object remains 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> Element configuration element. The default is 5 minutes. A lease time of 0 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 remote object is marked for garbage collection. If the value is 0 (TimeSpan.Zero), the lease does 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 the following 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 Framework remoting system that instances of this type have an infinite lifetime.

  • A developer or an administrator can also specify lifetime properties for all objects in a particular application in the <lifetime> Element element in the application or machine configuration file. For more information, see Initializing Leases.

Once created, a lease can be renewed in the following ways:

  • A client calls the Renew 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 Renewal method to request 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.

Note that it is possible for a malicious remoting client to abuse the lease system to mount a denial of service (DOS) attack against a remoting server. The malicious client sponsors many leases and then refuses to answer the server's renewal queries. This DOS attack is only possible if TypeFilterLevel is set to full.

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 Framework remoting system removes the object reference from its internal table. The garbage collection system then removes the lease and the object.

See Also

Tasks

How to: Override the InitializeLifetimeService Method
How to: Renew a Lease

Reference

Remoting Settings Schema
ILease
RemotingServices.GetLifetimeService
MarshalByRefObject.InitializeLifetimeService

Concepts

Remoting Example: Lifetimes
Initializing Leases
Renewing Leases

Other Resources

Object Activation and Lifetimes