package jobobject

import "github.com/Microsoft/hcsshim/internal/jobobject"

This package provides higher level constructs for the win32 job object API. Most of the core creation and management functions are already present in "golang.org/x/sys/windows" (CreateJobObject, AssignProcessToJobObject, etc.) as well as most of the limit information structs and associated limit flags. Whatever is not present from the job object API in golang.org/x/sys/windows is located in /internal/winapi.

https://docs.microsoft.com/en-us/windows/win32/procthread/job-objects

Index

Variables 

var (
	ErrAlreadyClosed = errors.New("the handle has already been closed")
	ErrNotRegistered = errors.New("job is not registered to receive notifications")
	ErrNotSilo       = errors.New("job is not a silo")
)

Types

type CPURateControlType 

type CPURateControlType uint32
const (
	WeightBased CPURateControlType = iota
	RateBased
)

type JobLimits 

type JobLimits struct {
	CPULimit           uint32
	CPUWeight          uint32
	MemoryLimitInBytes uint64
	MaxIOPS            int64
	MaxBandwidth       int64
}

JobLimits represents the resource constraints that can be applied to a job object.

type JobObject 

type JobObject struct {
	// contains filtered or unexported fields
}

JobObject is a high level wrapper around a Windows job object. Holds a handle to the job, a queue to receive iocp notifications about the lifecycle of the job and a mutex for synchronized handle access.

func Create 

func Create(ctx context.Context, options *Options) (_ *JobObject, err error)

Create creates a job object.

If options.Name is an empty string, the job will not be assigned a name.

If options.Notifications are not enabled `PollNotifications` will return immediately with error `errNotRegistered`.

If `options` is nil, use default option values.

Returns a JobObject structure and an error if there is one.

func Open 

func Open(ctx context.Context, options *Options) (_ *JobObject, err error)

Open opens an existing job object with name provided in `options`. If no name is provided return an error since we need to know what job object to open.

If options.Notifications is false `PollNotifications` will return immediately with error `errNotRegistered`.

Returns a JobObject structure and an error if there is one.

func (*JobObject) ApplyFileBinding 

func (job *JobObject) ApplyFileBinding(root, target string, readOnly bool) error

ApplyFileBinding makes a file binding using the Bind Filter from target to root. If the job has not been upgraded to a silo this call will fail. The binding is only applied and visible for processes running in the job, any processes on the host or in another job will not be able to see the binding.

func (*JobObject) Assign 

func (job *JobObject) Assign(pid uint32) error

Assign assigns a process to the job object.

func (*JobObject) Close 

func (job *JobObject) Close() error

Close closes the job object handle.

func (*JobObject) GetCPUAffinity 

func (job *JobObject) GetCPUAffinity() (uint64, error)

GetCPUAffinity gets the processor affinity for the job object. The returned affinity is a bitmask.

func (*JobObject) GetCPULimit 

func (job *JobObject) GetCPULimit(rateControlType CPURateControlType) (uint32, error)

GetCPULimit gets the cpu limits for the job object. `rateControlType` is used to indicate what type of cpu limit to query for.

func (*JobObject) GetIOMaxBandwidthLimit 

func (job *JobObject) GetIOMaxBandwidthLimit() (int64, error)

GetIOMaxBandwidthLimit gets the max bandwidth for the job object.

func (*JobObject) GetIOMaxIopsLimit 

func (job *JobObject) GetIOMaxIopsLimit() (int64, error)

GetIOMaxIopsLimit gets the max iops for the job object.

func (*JobObject) GetMemoryLimit 

func (job *JobObject) GetMemoryLimit() (uint64, error)

GetMemoryLimit gets the memory limit in bytes of the job object.

func (*JobObject) Pids 

func (job *JobObject) Pids() ([]uint32, error)

Pids returns all of the process IDs in the job object.

func (*JobObject) PollNotification 

func (job *JobObject) PollNotification() (interface{}, error)

PollNotification will poll for a job object notification. This call should only be called once per job (ideally in a goroutine loop) and will block if there is not a notification ready. This call will return immediately with error `ErrNotRegistered` if the job was not registered to receive notifications during `Create`. Internally, messages will be queued and there is no worry of messages being dropped.

func (*JobObject) PromoteToSilo 

func (job *JobObject) PromoteToSilo() error

PromoteToSilo promotes a job object to a silo. There must be no running processess in the job for this to succeed. If the job is already a silo this is a no-op.

func (*JobObject) QueryMemoryStats 

func (job *JobObject) QueryMemoryStats() (*winapi.JOBOBJECT_MEMORY_USAGE_INFORMATION, error)

QueryMemoryStats gets the memory stats for the job object.

func (*JobObject) QueryPrivateWorkingSet 

func (job *JobObject) QueryPrivateWorkingSet() (uint64, error)

QueryPrivateWorkingSet returns the private working set size for the job. This is calculated by adding up the private working set for every process running in the job.

func (*JobObject) QueryProcessorStats 

func (job *JobObject) QueryProcessorStats() (*winapi.JOBOBJECT_BASIC_ACCOUNTING_INFORMATION, error)

QueryProcessorStats gets the processor stats for the job object.

func (*JobObject) QueryStorageStats 

func (job *JobObject) QueryStorageStats() (*winapi.JOBOBJECT_IO_ATTRIBUTION_INFORMATION, error)

QueryStorageStats gets the storage (I/O) stats for the job object. This call will error if either `EnableIOTracking` wasn't set to true on creation of the job, or SetIOTracking() hasn't been called since creation of the job.

func (*JobObject) SetCPUAffinity 

func (job *JobObject) SetCPUAffinity(affinityBitMask uint64) error

SetCPUAffinity sets the processor affinity for the job object. The affinity is passed in as a bitmask.

func (*JobObject) SetCPULimit 

func (job *JobObject) SetCPULimit(rateControlType CPURateControlType, rateControlValue uint32) error

SetCPULimit sets the CPU limit depending on the specified `CPURateControlType` to `rateControlValue` for the job object.

func (*JobObject) SetIOLimit 

func (job *JobObject) SetIOLimit(maxBandwidth, maxIOPS int64) error

SetIOLimit sets the IO limits specified on the job object.

func (*JobObject) SetIOTracking 

func (job *JobObject) SetIOTracking() error

SetIOTracking enables IO tracking for processes in the job object. This enables use of the QueryStorageStats method.

func (*JobObject) SetMemoryLimit 

func (job *JobObject) SetMemoryLimit(memoryLimitInBytes uint64) error

SetMemoryLimit sets the memory limit of the job object based on the given `memoryLimitInBytes`.

func (*JobObject) SetResourceLimits 

func (job *JobObject) SetResourceLimits(limits *JobLimits) error

SetResourceLimits sets resource limits on the job object (cpu, memory, storage).

func (*JobObject) SetTerminateOnLastHandleClose 

func (job *JobObject) SetTerminateOnLastHandleClose() error

SetTerminateOnLastHandleClose sets the job object flag that specifies that the job should terminate all processes in the job on the last open handle being closed.

func (*JobObject) Terminate 

func (job *JobObject) Terminate(exitCode uint32) error

Terminate terminates the job, essentially calls TerminateProcess on every process in the job.

func (*JobObject) UpdateProcThreadAttribute 

func (job *JobObject) UpdateProcThreadAttribute(attrList *windows.ProcThreadAttributeListContainer) error

UpdateProcThreadAttribute updates the passed in ProcThreadAttributeList to contain what is necessary to launch a process in a job at creation time. This can be used to avoid having to call Assign() after a process has already started running.

type MsgAllProcessesExited 

type MsgAllProcessesExited struct{}

MsgAllProcessesExited is a type representing a message that every process in a job has exited.

type MsgUnimplemented 

type MsgUnimplemented struct{}

MsgUnimplemented represents a message that we are aware of, but that isn't implemented currently. This should not be treated as an error.

type Options 

type Options struct {
	// `Name` specifies the name of the job object if a named job object is desired.
	Name string
	// `Notifications` specifies if the job will be registered to receive notifications.
	// Defaults to false.
	Notifications bool
	// `UseNTVariant` specifies if we should use the `Nt` variant of Open/CreateJobObject.
	// Defaults to false.
	UseNTVariant bool
	// `Silo` specifies to promote the job to a silo. This additionally sets the flag
	// JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE as it is required for the upgrade to complete.
	Silo bool
	// `IOTracking` enables tracking I/O statistics on the job object. More specifically this
	// calls SetInformationJobObject with the JobObjectIoAttribution class.
	EnableIOTracking bool
}

Options represents the set of configurable options when making or opening a job object.

Source Files

doc.go iocp.go jobobject.go limits.go

Version
v0.13.0 (latest)
Published
Apr 21, 2025
Platform
windows/amd64
Imports
13 packages
Last checked
17 hours ago –

Tools for package owners.