JobObject Class

Namespace: Meziantou.Framework.Win32
Assembly: Meziantou.Framework.Win32.Jobs.dll
Package: Meziantou.Framework.Win32.Jobs 4.0.8
Source: JobObject.cs
Available in package assets: net10.0net11.0

Supported on windows5.1.2600

A utility class that represents a Windows job object. Job objects allow groups of processes to be managed as a unit.

[SupportedOSPlatform("windows5.1.2600")]
public sealed class JobObject : IDisposable

Example

using var job = new JobObject();
job.SetLimits(new JobObjectLimits
{
    Flags = JobObjectLimitFlags.KillOnJobClose,
});

// Start a child process and assign it to the job
using var childProcess = Process.Start(new ProcessStartInfo("ping", "127.0.0.1 -n 100") { CreateNoWindow = true })!;
job.AssignProcess(childProcess);

// Disposing the job terminates the child process
job.Dispose();
childProcess.WaitForExit();

Implements

IDisposable

Constructors

Name	Description
JobObject()	Initializes a new instance of the `JobObject` class. The associated job object will have no name.
JobObject(string?)	Initializes a new instance of the `JobObject` class.
JobObject(string?, bool)	Initializes a new instance of the `JobObject` class.

JobObject overloads

JobObject()

JobObject.cs

Initializes a new instance of the JobObject class. The associated job object will have no name.

public JobObject()

JobObject(string?)

JobObject.cs

Initializes a new instance of the JobObject class.

public JobObject(string? name)

Parameters

name string?: The job object name. May be null.

JobObject(string?, bool)

JobObject.cs

Initializes a new instance of the JobObject class.

public JobObject(string? name, bool inheritHandle)

Parameters

name string?: The job object name. May be null.
inheritHandle bool: A Boolean value that specifies whether the returned handle is inherited when a new process is created. If this member is true, the new process inherits the handle.

Remarks

When name matches a job object that already exists, this attaches to that job object instead of creating a new one. Inspect JobObject.CreatedNew to tell the two apart.

Properties

Name	Description
CreatedNew	Gets a value indicating whether this instance created the underlying job object.

CreatedNew

JobObject.cs

Gets a value indicating whether this instance created the underlying job object.

public bool CreatedNew { get; }

Property value

bool true when the constructor created a new job object; false when a job object with the requested name already existed and this instance attached to it, or when the instance was returned by JobObject.Open or JobObject.TryOpen.

Remarks

Job objects share a namespace with events, semaphores, mutexes, waitable timers and file-mapping objects, and CreateJobObject returns a handle to the existing object rather than failing when the name is taken. Check this property when the caller needs an isolated job: attaching to a job created elsewhere means inheriting its limits, its process set and its lifetime.

Methods

Name	Description
AssignProcess(Process)	Assigns a process to an existing job object.
AssignProcess(nint)	Assigns a process to an existing job object.
DisableCpuRateHardCap()	Disables the job's CPU rate limit.
Dispose()
GetBasicAccountingInformation()	Get the job's basic accounting information.
GetBasicAndIoAccountingInformation()	Get the job's basic and IO accounting information.
GetCpuRateHardCap()	Get the job's CPU rate control policy and the values that belong to it.
GetMemoryAccountingInformation()	Get the job's memory accounting information.
IsAssignedToProcess(Process)	Determines whether the specified process is assigned to this job object.
Open(JobObjectAccessRights, bool, string)	Opens an existing job object.
SetCpuRate(int, int)	Set the job's CPU rate is a hard limit. After the job reaches its CPU cycle limit for the current scheduling interval, no threads associated with the job will run until the next interval.
SetCpuRateHardCap(int)	Set the job's CPU rate is a hard limit. After the job reaches its CPU cycle limit for the current scheduling interval, no threads associated with the job will run until the next interval.
SetCpuRateWeight(int)	Set the job's CPU rate is calculated based on its relative weight to the weight of other jobs.
SetIoLimits(JobIoRateLimits)	Sets I/O limits on a job object.
SetLimits(JobObjectLimits)	Sets limits to the job.
SetNetRateLimits(ulong)	Set bandwidth limits for the job.
SetSecurityLimits(JobObjectSecurityLimit)	Set security limits for the job.
SetUIRestrictions(JobObjectUILimit)	Sets UI restrictions for processes in the job.
Terminate()	Terminates all processes currently associated with the job. If the job is nested, this function terminates all processes currently associated with the job and all of its child jobs in the hierarchy.
Terminate(int)	Terminates all processes currently associated with the job. If the job is nested, this function terminates all processes currently associated with the job and all of its child jobs in the hierarchy.
TryOpen(JobObjectAccessRights, bool, string, JobObject?)	Attempts to open an existing job object.

AssignProcess overloads

AssignProcess(Process)

JobObject.cs

Assigns a process to an existing job object.

public void AssignProcess(Process process)

Parameters

process Process: The process.

AssignProcess(nint)

JobObject.cs

Assigns a process to an existing job object.

public void AssignProcess(nint processHandle)

Parameters

processHandle nint: The process handle.

Remarks

The caller must keep processHandle open for the duration of the call. Prefer JobObject.AssignProcess when a Process instance is available.

DisableCpuRateHardCap()

JobObject.cs

Disables the job's CPU rate limit.

public void DisableCpuRateHardCap()

Dispose()

JobObject.cs

public void Dispose()

No documentation is available.

GetBasicAccountingInformation()

JobObject.cs

Get the job's basic accounting information.

public JobObjectBasicAccountingInformation GetBasicAccountingInformation()

Returns

JobObjectBasicAccountingInformation JobObjectBasicAccountingInformation record containing basic accounting information.

Exceptions

Win32Exception: The operation failed.

GetBasicAndIoAccountingInformation()

JobObject.cs

Get the job's basic and IO accounting information.

public JobObjectBasicAndIoAccountingInformation GetBasicAndIoAccountingInformation()

Returns

JobObjectBasicAndIoAccountingInformation JobObjectBasicAndIoAccountingInformation record containing both basic and IO accounting information.

Exceptions

Win32Exception: The operation failed.

GetCpuRateHardCap()

JobObject.cs

Get the job's CPU rate control policy and the values that belong to it.

public JobObjectCpuHardCap GetCpuRateHardCap()

Returns

JobObjectCpuHardCap A JobObjectCpuHardCap describing the active policy. Windows stores the rate, the weight and the min/max pair in a union, so only the members matching JobObjectCpuHardCap.Mode carry a meaningful value.

Exceptions

Win32Exception: The operation failed.

GetMemoryAccountingInformation()

JobObject.cs

Get the job's memory accounting information.

public JobObjectMemoryAccountingInformation GetMemoryAccountingInformation()

Returns

JobObjectMemoryAccountingInformation JobObjectMemoryAccountingInformation record containing memory accounting information.

Exceptions

Win32Exception: The operation failed.

IsAssignedToProcess(Process)

JobObject.cs

Determines whether the specified process is assigned to this job object.

public bool IsAssignedToProcess(Process process)

Parameters

process Process: The process to check.

Returns

bool true if the process is assigned to the job object; otherwise, false.

Exceptions

ArgumentNullException: process is null.
Win32Exception: The operation failed.

Open(JobObjectAccessRights, bool, string)

JobObject.cs

Opens an existing job object.

public static JobObject Open(JobObjectAccessRights desiredAccess, bool inherited, string name)

Parameters

desiredAccess JobObjectAccessRights: The access rights for the job object.
inherited bool: If this value is true, processes created by this process will inherit the handle. Otherwise, the processes do not inherit this handle.
name string: The name of the job object to be opened.

Returns

JobObject A JobObject instance representing the opened job object.

Exceptions

Win32Exception: The job object could not be opened.

SetCpuRate(int, int)

JobObject.cs

Set the job's CPU rate is a hard limit. After the job reaches its CPU cycle limit for the current scheduling interval, no threads associated with the job will run until the next interval.

public void SetCpuRate(int minRate, int maxRate)

Parameters

minRate int: Specifies the minimum portion of the processor cycles that the threads in a job object can reserve during each scheduling interval. Specify this rate as a percentage times 100. For example, to set a minimum rate of 50%, specify 50 times 100, or 5,000.
maxRate int: Specifies the maximum portion of processor cycles that the threads in a job object can use during each scheduling interval. Specify this rate as a percentage times 100. For example, to set a maximum rate of 50%, specify 50 times 100, or 5,000. After the job reaches this limit for a scheduling interval, no threads associated with the job can run until the next scheduling interval.

Exceptions

ArgumentOutOfRangeException: minRate or maxRate is not between 1 and 10,000, or minRate is greater than maxRate.

SetCpuRateHardCap(int)

JobObject.cs

Set the job's CPU rate is a hard limit. After the job reaches its CPU cycle limit for the current scheduling interval, no threads associated with the job will run until the next interval.

public void SetCpuRateHardCap(int cpuRate)

Parameters

cpuRate int: Specifies the portion of processor cycles that the threads in a job object can use during each scheduling interval, as the number of cycles per 10,000 cycles. For example, to let the job use 20% of the CPU, set CpuRate to 20 times 100, or 2,000.

Exceptions

ArgumentOutOfRangeException: cpuRate is not between 1 and 10,000.

SetCpuRateWeight(int)

JobObject.cs

Set the job's CPU rate is calculated based on its relative weight to the weight of other jobs.

public void SetCpuRateWeight(int weight)

Parameters

weight int: Specifies the scheduling weight of the job object, which determines the share of processor time given to the job relative to other workloads on the processor. This member can be a value from 1 through 9, where 1 is the smallest share and 9 is the largest share.The default is 5, which should be used for most workloads.

Exceptions

ArgumentOutOfRangeException: weight is not between 1 and 9.

SetIoLimits(JobIoRateLimits)

JobObject.cs

Supported on windows10.0.10240

Sets I/O limits on a job object.

[SupportedOSPlatform("windows10.0.10240")]
public void SetIoLimits(JobIoRateLimits limits)

Parameters

limits JobIoRateLimits

SetLimits(JobObjectLimits)

JobObject.cs

Sets limits to the job.

public void SetLimits(JobObjectLimits limits)

Parameters

limits JobObjectLimits: The limits. May not be null.

SetNetRateLimits(ulong)

JobObject.cs

Set bandwidth limits for the job.

public void SetNetRateLimits(ulong maxBandwidth)

Parameters

maxBandwidth ulong: The maximum bandwidth for outgoing network traffic for the job, in bytes.

SetSecurityLimits(JobObjectSecurityLimit)

JobObject.cs

Set security limits for the job.

public void SetSecurityLimits(JobObjectSecurityLimit securityLimit)

Parameters

securityLimit JobObjectSecurityLimit

SetUIRestrictions(JobObjectUILimit)

JobObject.cs

Sets UI restrictions for processes in the job.

public void SetUIRestrictions(JobObjectUILimit limits)

Parameters

limits JobObjectUILimit: The UI restrictions to apply to the job.

Exceptions

Win32Exception: The UI restrictions could not be set.

Terminate overloads

Terminate()

JobObject.cs

Terminates all processes currently associated with the job. If the job is nested, this function terminates all processes currently associated with the job and all of its child jobs in the hierarchy.

public void Terminate()

Exceptions

Win32Exception: The processes could not be terminated.

Terminate(int)

JobObject.cs

Terminates all processes currently associated with the job. If the job is nested, this function terminates all processes currently associated with the job and all of its child jobs in the hierarchy.

public void Terminate(int exitCode)

Parameters

exitCode int: The exit code to be used by all processes and threads in the job object.

Exceptions

Win32Exception: The processes could not be terminated. This happens when the handle does not have the JobObjectAccessRights.Terminate access right.

TryOpen(JobObjectAccessRights, bool, string, JobObject?)

JobObject.cs

Attempts to open an existing job object.

public static bool TryOpen(JobObjectAccessRights desiredAccess, bool inherited, string name, out JobObject? jobObject)

Parameters

desiredAccess JobObjectAccessRights: The access rights for the job object.
inherited bool: If this value is true, processes created by this process will inherit the handle. Otherwise, the processes do not inherit this handle.
name string: The name of the job object to be opened.
jobObject JobObject?: When this method returns, contains the opened job object if the operation succeeded, or null if the job object was not found.

Returns

bool true if the job object was successfully opened; otherwise, false.

Exceptions

Win32Exception: An error occurred while attempting to open the job object (other than the job object not being found).