package jobobject

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

Index

Variables 

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

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) 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) 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
	// `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

iocp.go jobobject.go limits.go

Version
v0.9.5
Published
Oct 31, 2022
Platform
js/wasm
Imports
10 packages
Last checked
6 seconds ago –

Tools for package owners.