System.WeakReference Class

Assembly: Mscorlib.dll
Namespace: System
Summary
Represents a weak reference, which references an object while still allowing it to be garbage collected.
C# Syntax:
[Serializable]
public class WeakReference : ISerializable
Remarks
The common language runtime garbage collection mechanism reclaims inaccessible (that is, unreachable) memory allocated to an object. An object becomes unreachable if all references to it become invalid, for example, by setting those references to null.

Garbage collection will call an object's Object.Finalize method (that is, perform finalization), if there is such a method and if instructed to do so. Once finalization is complete, unpredictable results will occur if the garbage collected object is reacquired somehow and reused.

A directly or indirectly referenced object is reachable, and the garbage collector is not permitted to reclaim it. A reference to a reachable object is called a strong reference.

A weak reference also references a reachable object, which is called the target. A user acquires a strong reference to the target by assigning the value of the WeakReference.Target property to a variable. However, if there are no strong references to the target, the target becomes eligible for garbage collection even though it still has a weak reference.

There can be a delay between the time an object becomes eligible for garbage collection and the time it is collected. If the user attempts to retrieve the target after it has been collected, only a null reference will be retrieved. If the target has not yet been collected, a valid reference will be retrieved.

An object can be used (that is, be alive); become unused and eligible for garbage collection (that is, dead); then used again (that is, resurrected). However, unpredictable behavior results if a resurrected object is accessed after finalization.

A WeakReference object can specify whether the reference to its target be maintained after finalization; that is, whether the weak reference should track the target's resurrection. A weak reference that does not track resurrection is called a short weak reference, and a weak reference that tracks resurrection is called a long weak reference.

See also:
System Namespace | GC | WeakReference.Finalize

System.WeakReference Member List:

Public Constructors
ctor #1 Overloaded:
.ctor(object target)

Initializes a new instance of the WeakReference class, referencing the specified object.
ctor #2 Overloaded:
.ctor(object target, bool trackResurrection)

Initializes a new instance of the WeakReference class, referencing the specified object and using the specified resurrection tracking.
Public Properties
IsAlive Read-only

Gets an indication whether the object referenced by this instance has been garbage collected.
Target Read-write

Gets or sets the object (the target) referenced by this instance.
TrackResurrection Read-only

Gets an indication whether the object referenced by this instance is tracked after it is garbage collected and finalized.
Public Methods
Equals
(inherited from System.Object)
See base class member description: System.Object.Equals

Derived from System.Object, the primary base class for all objects.
GetHashCode
(inherited from System.Object)
See base class member description: System.Object.GetHashCode

Derived from System.Object, the primary base class for all objects.
GetObjectData Populates a SerializationInfo object with all the data needed to serialize this instance.
GetType
(inherited from System.Object)
See base class member description: System.Object.GetType

Derived from System.Object, the primary base class for all objects.
ToString
(inherited from System.Object)
See base class member description: System.Object.ToString

Derived from System.Object, the primary base class for all objects.
Protected Constructors
ctor #3 Overloaded:
.ctor(SerializationInfo info, StreamingContext context)

Initializes a new instance of the WeakReference class, using deserialized data from the specified serialization and stream objects.
Protected Methods
Finalize Overridden:
Frees any resources allocated by this instance.
MemberwiseClone
(inherited from System.Object)
See base class member description: System.Object.MemberwiseClone

Derived from System.Object, the primary base class for all objects.

Hierarchy:


System.WeakReference Member Details

Overloaded ctor #1
Summary
Initializes a new instance of the WeakReference class, referencing the specified object.
C# Syntax:
public WeakReference(
   object target
);
Parameters:

target

The object to track or null.

Remarks
This constructor creates a short weak reference to target.
See also:
Object

Return to top


Overloaded ctor #2
Summary
Initializes a new instance of the WeakReference class, referencing the specified object and using the specified resurrection tracking.
C# Syntax:
public WeakReference(
   object target,
   bool trackResurrection
);
Parameters:

target

An object to track.

trackResurrection

Indicates when to stop tracking the object. If true, the object is tracked after finalization; if false, the object is only tracked until finalization.

Remarks
If trackResurrection is false, a short weak reference is created. If trackResurrection is true, a long weak reference is created. Typically, only short weak references are needed.
See also:
Object | Boolean | GCHandle

Return to top


Overloaded ctor #3
Summary
Initializes a new instance of the WeakReference class, using deserialized data from the specified serialization and stream objects.
C# Syntax:
protected WeakReference(
   SerializationInfo info,
   StreamingContext context
);
Parameters:

info

An object that holds all the data needed to serialize or deserialize this instance.

context

(Reserved) Describes the source and destination of the serialized stream specified by info.

Exceptions
Exception Type Condition
ArgumentNullException info is null.
Remarks
The context parameter is reserved, and does not currently participate in this operation.

Return to top


Property: IsAlive (read-only)
Summary
Gets an indication whether the object referenced by this instance has been garbage collected.
C# Syntax:
public virtual bool IsAlive {get;}
Exceptions
Exception Type Condition
InvalidOperationException The reference to the target object is invalid.
Remarks
An exception is thrown if the object referenced by this instance is invalid. This can occur if there is an attempt to resurrect the referenced object after it has been finalized.
See also:
GC | Object

Return to top


Property: Target (read-write)
Summary
Gets or sets the object (the target) referenced by this instance.
C# Syntax:
public virtual object Target {get; set;}
Exceptions
Exception Type Condition
InvalidOperationException The reference to the target object is invalid.
Remarks
An exception is thrown if the reference to the object referenced by this instance is invalid. This can occur if there is an attempt to resurrect the referenced object after it has been finalized.
See also:
Object | GC

Return to top


Property: TrackResurrection (read-only)
Summary
Gets an indication whether the object referenced by this instance is tracked after it is garbage collected and finalized.
C# Syntax:
public virtual bool TrackResurrection {get;}
See also:
GC

Return to top


Method: Equals(
   object obj
)
Inherited
See base class member description: System.Object.Equals
C# Syntax:
public virtual bool Equals(
   object obj
);

For more information on members inherited from System.Object click on the link above.

Return to top


Overridden Method: Finalize()
Summary
Frees any resources allocated by this instance.
C# Syntax:
~WeakReference();
See also:
GC | Object.Finalize

Return to top


Method: GetHashCode()
Inherited
See base class member description: System.Object.GetHashCode
C# Syntax:
public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: GetObjectData(
   SerializationInfo info,
   StreamingContext context
)
Summary
Populates a SerializationInfo object with all the data needed to serialize this instance.
C# Syntax:
public virtual void GetObjectData(
   SerializationInfo info,
   StreamingContext context
);
Parameters:

info

An object that holds all the data needed to serialize or deserialize this instance.

context

(Reserved) The location where serialized data will be stored and retrieved.

Exceptions
Exception Type Condition
ArgumentNullException info is null.
Implements:
ISerializable.GetObjectData
Remarks
This method stores all the information in info necessary to serialize this instance.

The context parameter is reserved and is not currently used in the execution of this method.

See also:
Object | SerializationInfo

Return to top


Method: GetType()
Inherited
See base class member description: System.Object.GetType
C# Syntax:
public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: MemberwiseClone()
Inherited
See base class member description: System.Object.MemberwiseClone
C# Syntax:
protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: ToString()
Inherited
See base class member description: System.Object.ToString
C# Syntax:
public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top


Top of page

Copyright (c) 2002 Microsoft Corporation. All rights reserved.