System.Threading.Interlocked Class

Assembly: Mscorlib.dll
Namespace: System.Threading
Summary
Provides atomic operations for variables that are shared by multiple threads.
C# Syntax:
public sealed class Interlocked
Remarks
The methods of this class protect against errors that can occur when the scheduler switches contexts while a thread is updating a variable that can be accessed by other threads. The members of this class do not throw exceptions.

The Interlocked.Increment and Interlocked.Decrement methods increment or decrement a variable and store the resulting value in a single operation. This atomic operation is useful in a multitasking operating system, where the system can interrupt one thread's execution to grant a slice of processor time to another thread. For example, without such synchronization, one thread could increment a variable but be interrupted by the system before it can check the resulting value of the variable. A second thread could then increment the same variable. When the first thread receives its next time slice, it will check the value of the variable, which has now been incremented not once but twice. The Interlocked methods protect against this kind of error.

The Interlocked.Exchange method atomically exchanges the values of the specified variables. The Interlocked.CompareExchange method combines two operations: comparing two values and storing a third value in one of the variables, based on the outcome of the comparison. The compare and exchange operations are performed as an atomic operation.

See also:
System.Threading Namespace

System.Threading.Interlocked Member List:

Public Methods
CompareExchange Overloaded:
CompareExchange(ref int location1, int value, int comparand)

Compares two 32-bit signed integers for equality and, if they are equal, replaces one of the values.
CompareExchange Overloaded:
CompareExchange(ref object location1, object value, object comparand)

Compares two objects for equality and, if they are equal, replaces one of the objects.
CompareExchange Overloaded:
CompareExchange(ref float location1, float value, float comparand)

Compares two single-precision floating point numbers for equality and, if they are equal, replaces one of the values.
CompareExchangePointer
Decrement Overloaded:
Decrement(ref int location)

Decrements a specified variable and stores the result, as an atomic operation.
Decrement Overloaded:
Decrement(ref long location)

Decrements the specified variable and stores the result, as an atomic operation.
Equals
(inherited from System.Object)
See base class member description: System.Object.Equals

Derived from System.Object, the primary base class for all objects.
Exchange Overloaded:
Exchange(ref int location1, int value)

Sets a 32-bit signed integer to a specified value as an atomic operation, and returns the original value.
Exchange Overloaded:
Exchange(ref object location1, object value)

Sets an object to a specified value as an atomic operation, and returns a reference to the original object.
Exchange Overloaded:
Exchange(ref float location1, float value)

Sets a single-precision floating point number to a specified value as an atomic operation, and returns the original value.
GetHashCode
(inherited from System.Object)
See base class member description: System.Object.GetHashCode

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

Derived from System.Object, the primary base class for all objects.
Increment Overloaded:
Increment(ref int location)

Increments a specified variable and stores the result, as an atomic operation.
Increment Overloaded:
Increment(ref long location)

Increments a specified variable and stores the result, as an atomic operation.
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 Methods
Finalize
(inherited from System.Object)
See base class member description: System.Object.Finalize

Derived from System.Object, the primary base class for all objects.
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.Threading.Interlocked Member Details

Overloaded Method: CompareExchange(
   ref int location1,
   int value,
   int comparand
)
Summary
Compares two 32-bit signed integers for equality and, if they are equal, replaces one of the values.
C# Syntax:
public static int CompareExchange(
   ref int location1,
   int value,
   int comparand
);
Parameters:

location1

The destination value that will be compared with the value of the comparand parameter and will possibly be replaced. The destination value that will be compared with the value of the comparand parameter and will possibly be replaced.

value

The value that will replace the destination value if the comparison results in equality.

comparand

The value to be compared to the location1 parameter.

Return Value:
The original value of the location1 parameter.
Remarks
If comparand and location1 are equal, then value is stored in the destination. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation.

Return to top


Overloaded Method: CompareExchange(
   ref object location1,
   object value,
   object comparand
)
Summary
Compares two objects for equality and, if they are equal, replaces one of the objects.
C# Syntax:
public static object CompareExchange(
   ref object location1,
   object value,
   object comparand
);
Parameters:

location1

The destination object that will be compared with the value of the comparand parameter and will possibly be replaced.

value

The object that will replace the destination object if the comparison results in equality.

comparand

The object to be compared to the location1 parameter.

Return Value:
The original value of the location1 parameter.
Exceptions
Exception Type Condition
ArgumentNullException The address of location1 is null.
Remarks
If comparand and location1 are equal, then value is stored in the destination. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation.

Return to top


Overloaded Method: CompareExchange(
   ref float location1,
   float value,
   float comparand
)
Summary
Compares two single-precision floating point numbers for equality and, if they are equal, replaces one of the values.
C# Syntax:
public static float CompareExchange(
   ref float location1,
   float value,
   float comparand
);
Parameters:

location1

The destination value that will be compared with the value of the comparand parameter and will possibly be replaced.

value

The value that will replace the destination value if the comparison results in equality.

comparand

The value to be compared to the location1 parameter.

Return Value:
The original destination value.
Remarks
If comparand and location1 are equal, then value is stored in the destination. Otherwise, no operation is performed. The compare and exchange operations are performed in an atomic operation.

Return to top


Method: CompareExchangePointer(
   ref IntPtr location1,
   IntPtr value,
   IntPtr comparand
)
C# Syntax:
public static IntPtr CompareExchangePointer(
   ref IntPtr location1,
   IntPtr value,
   IntPtr comparand
);
Parameters:

location1

value

comparand

Return to top


Overloaded Method: Decrement(
   ref int location
)
Summary
Decrements a specified variable and stores the result, as an atomic operation.
C# Syntax:
public static int Decrement(
   ref int location
);
Parameters:

location

The variable whose value is to be decremented.

Return Value:
The decremented value.
Remarks
This method handles an overflow condition by wrapping: If location = Int32.MinValue, location - 1 = Int32.MaxValue. No exception is thrown.

Return to top


Overloaded Method: Decrement(
   ref long location
)
Summary
Decrements the specified variable and stores the result, as an atomic operation.
C# Syntax:
public static long Decrement(
   ref long location
);
Parameters:

location

The variable whose value is to be decremented.

Return Value:
The decremented value.
Remarks
This method handles an overflow condition by wrapping: if location = Int64.MinValue, location - 1 = Int64.MaxValue. No exception is thrown.

The 64-bit versions of Interlocked.Increment and Decrement are truly atomic only on systems where a IntPtr is 64 bits long. On other systems, these methods are atomic with respect to each other, but not with respect to other means of accessing the data.

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


Overloaded Method: Exchange(
   ref int location1,
   int value
)
Summary
Sets a 32-bit signed integer to a specified value as an atomic operation, and returns the original value.
C# Syntax:
public static int Exchange(
   ref int location1,
   int value
);
Parameters:

location1

The variable to set to the specified value.

value

The value to which the location1 parameter is set.

Return Value:
The original value of location1.

Return to top


Overloaded Method: Exchange(
   ref object location1,
   object value
)
Summary
Sets an object to a specified value as an atomic operation, and returns a reference to the original object.
C# Syntax:
public static object Exchange(
   ref object location1,
   object value
);
Parameters:

location1

The variable to set to the specified.

value

The value to which the location1 parameter is set.

Return Value:
The original value of location1.
Exceptions
Exception Type Condition
ArgumentNullException The address of location1 is null.

Return to top


Overloaded Method: Exchange(
   ref float location1,
   float value
)
Summary
Sets a single-precision floating point number to a specified value as an atomic operation, and returns the original value.
C# Syntax:
public static float Exchange(
   ref float location1,
   float value
);
Parameters:

location1

The variable to set to the specified value.

value

The value to which the location1 parameter is set.

Return Value:
The original value of location1.

Return to top


Method: Finalize()
Inherited
See base class member description: System.Object.Finalize
C# Syntax:
~Interlocked();

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

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: 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


Overloaded Method: Increment(
   ref int location
)
Summary
Increments a specified variable and stores the result, as an atomic operation.
C# Syntax:
public static int Increment(
   ref int location
);
Parameters:

location

The variable whose value is to be incremented.

Return Value:
The incremented value.
Remarks
This method handles an overflow condition by wrapping: if location = Int32.MaxValue, location + 1 = Int32.MinValue. No exception is thrown.

Return to top


Overloaded Method: Increment(
   ref long location
)
Summary
Increments a specified variable and stores the result, as an atomic operation.
C# Syntax:
public static long Increment(
   ref long location
);
Parameters:

location

The variable whose value is to be incremented.

Return Value:
The incremented value.
Remarks
This method handles an overflow condition by wrapping: if location = Int64.MaxValue, location + 1 = Int64.MinValue. No exception is thrown.

The 64-bit versions of Increment and Interlocked.Decrement are truly atomic only on systems where a IntPtr is 64 bits long. On other systems, these methods are atomic with respect to each other, but not with respect to other means of accessing the data.

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.