SuppressGCTransitionAttribute Class

Definition

Namespace:

System.Runtime.InteropServices

Assembly:

System.Runtime.dll

Source:

SuppressGCTransitionAttribute.cs

Indicates that a garbage collection transition should be skipped when an unmanaged function call is made.

public ref class SuppressGCTransitionAttribute sealed : Attribute

[System.AttributeUsage(System.AttributeTargets.Method, Inherited=false)]
public sealed class SuppressGCTransitionAttribute : Attribute

[<System.AttributeUsage(System.AttributeTargets.Method, Inherited=false)>]
type SuppressGCTransitionAttribute = class
    inherit Attribute

Public NotInheritable Class SuppressGCTransitionAttribute
Inherits Attribute

Inheritance

Object

Attribute

SuppressGCTransitionAttribute

Attributes

AttributeUsageAttribute

Remarks

This attribute is ignored if applied to a method without the DllImportAttribute.

Forgoing this transition can yield benefits when the cost of the transition is more than the execution time of the unmanaged function. However, avoiding this transition removes some of the guarantees the runtime provides through a normal P/Invoke. When exiting the managed runtime to enter an unmanaged function, the GC must transition from Cooperative mode into Preemptive mode. Full details on these modes can be found at https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/clr-code-guide.md#2.1.8. Suppressing the GC transition is an advanced scenario and should not be done without fully understanding potential consequences.

One of these consequences is an impact to Mixed-mode debugging. During Mixed-mode debugging, it is not possible to step into or set breakpoints in a P/Invoke that has been marked with this attribute. A workaround is to switch to native debugging and set a breakpoint in the native function. In general, usage of this attribute is not recommended if debugging the P/Invoke is important, for example, stepping through the native code or diagnosing an exception thrown from the native code.

The P/Invoke method that this attribute is applied to must have all of the following properties:

• Native function always executes for a trivial amount of time (less than 1 microsecond).
• Native function does not perform a blocking syscall (for example, any type of I/O).
• Native function does not call back into the runtime (for example, Reverse P/Invoke).
• Native function does not throw exceptions.
• Native function does not manipulate locks or other concurrency primitives.

Consequences of invalid uses of this attribute include:

• GC starvation.
• Immediate runtime termination.
• Data corruption.

Applying this attribute can cause the P/Invoke export to be bound earlier as a side-effect of the calling method being JIT compiled. EntryPointNotFoundException or other exceptions might be thrown earlier than when the attribute is not applied.

Constructors

SuppressGCTransitionAttribute()

Instance constructor.

Properties

TypeId

When implemented in a derived class, gets a unique identifier for this Attribute. (Inherited from Attribute)

Methods

Equals(Object)	Returns a value that indicates whether this instance is equal to a specified object. (Inherited from Attribute)
GetHashCode()	Returns the hash code for this instance. (Inherited from Attribute)
GetType()	Gets the Type of the current instance. (Inherited from Object)
IsDefaultAttribute()	When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class. (Inherited from Attribute)
Match(Object)	When overridden in a derived class, returns a value that indicates whether this instance equals a specified object. (Inherited from Attribute)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ToString()	Returns a string that represents the current object. (Inherited from Object)