Job Objects

A job object is a nameable, securable, shareable kernel object that allows control of one or more processes as a group. A job object's basic function is to allow groups of processes to be managed and manipulated as a unit. A process can be a member of only one job object. By default, its association with the job object can't be broken and all processes created by the process and its descendents are associated with the same job object as well. The job object also records basic accounting information for all processes associated with the job and for all processes that were associated with the job but have since terminated. Table 6-20 lists the Windows functions to create and manipulate job objects.

Table 6-19. Windows API Functions for Jobs

Function	Description
CreateJobObject	Creates a job object (with an optional name)
OpenJobObject	Opens an existing job object by name
AssignProcessToJobObject	Adds a process to a job
TerminateJobObject	Terminates all processes in a job
SetInformationJobObject	Sets limits
QueryInformationJobObject	Retrieves information about the job, such as CPU time, page fault count, number of processes, list of process IDs, quotas or limits, and security limits

The following are some of the CPU-related and memory-related limits you can specify for a job:

• Maximum number of active processes Limits the number of concurrently existing processes in the job.

• Jobwide user-mode CPU time limit Limits the maximum amount of user-mode CPU time that the processes in the job can consume (including processes that have run and exited). Once this limit is reached, by default all the processes in the job will be terminated with an error code and no new processes can be created in the job (unless the limit is reset). The job object is signaled, so any threads waiting for the job will be released. You can change this default behavior with a call to EndOfJobTimeAction.

• Per-process user-mode CPU time limit Allows each process in the job to accumulate only a fixed maximum amount of user-mode CPU time. When the maximum is reached, the process terminates (with no chance to clean up).

• Job scheduling class Sets the length of the time slice (or quantum) for threads in processes in the job. This setting applies only to systems running with long, fixed quantums (the default for Windows Server systems). The value of the job-scheduling class determines the quantum as shown here:

  Scheduling Class	Quantum Units
  0	6
  1	12
  2	18
  3	24
  4	30
  5	36
  6	42
  7	48
  8	54
  9	Infinite if real-time; 60 otherwise

  
  

• Job processor affinity Sets the processor affinity mask for each process in the job. (Individual threads can alter their affinity to any subset of the job affinity, but processes can't alter their process affinity setting.)

• Job process priority class Sets the priority class for each process in the job. Threads can't increase their priority relative to the class (as they normally can). Attempts to increase thread priority are ignored. (No error is returned on calls to SetThreadPriority, but the increase doesn't occur.)

• Default working set minimum and maximum Defines the specified working set minimum and maximum for each process in the job. (This setting isn't jobwide each process has its own working set with the same minimum and maximum values.)

• Process and job committed virtual memory limit Defines the maximum amount of virtual address space that can be committed by either a single process or the entire job.

Jobs can also be set to queue an entry to an I/O completion port object, which other threads might be waiting for, with the Windows GetQueuedCompletionStatus function.

You can also place security limits on processes in a job. You can set a job so that each process runs under the same jobwide access token. You can then create a job to restrict processes from impersonating or creating processes that have access tokens that contain the local administrator's group. In addition, you can apply security filters so that when threads in processes contained in a job impersonate client threads, certain privileges and security IDs (SIDs) can be eliminated from the impersonation token.

Finally, you can also place user-interface limits on processes in a job. Such limits include being able to restrict processes from opening handles to windows owned by threads outside the job, reading and/or writing to the clipboard, and changing the many user-interface system parameters via the Windows SystemParametersInfo function.

Windows 2000 Datacenter Server has a tool called the Process Control Manager that allows an administrator to define job objects, the various quotas and limits that can be specified for a job, and which processes, if run, should be added to the job. A service component monitors process activity and adds the specified processes to the jobs. Note that this tool is no longer shipped with Windows Server 2003 Datacenter Edition, but will remain on the system if a Windows 2000 Datacenter Server is upgraded to Windows Server 2003 Datacenter Edition.

EXPERIMENT: Viewing the Job Object

You can view named job objects with the Performance tool. (See the Job Object and Job Object Details performance objects.) You can view unnamed jobs with the kernel debugger !job or dt nt!_ejob commands.

To see whether a process is associated with a job, you can use the kernel debugger !process command, or on Windows XP and Windows Server 2003, Process Explorer. Follow these steps to create and view an unnamed job object:

1. From the command prompt, use the runas command to create a process running the command prompt (Cmd.exe). For example, type runas /user:<domain>\< username> cmd. You'll be prompted for your password. Enter your password, and a command prompt window will appear. The Windows service that executes runas commands creates an unnamed job to contain all processes (so that it can terminate these processes at logoff time).

2. From the command prompt, run Notepad.exe.

3. Then run Process Explorer and notice that the Cmd.exe and Notepad.exe processes are highlighted as part of a job. (You can configure the colors used to highlight processes that are members of a job by clicking Options, Configure Highlighting.) Here is a screen shot showing these two processes:

   
   
   
   
   

4. Double-click either the Cmd.exe or Notepad.exe process to bring up the process properties. You will see a Job tab on the process properties dialog box.

5. Click the Job tab to view the details about the job. In this case, there are no quotas associated with the job, but there are two member processes:

   
   

   

   
   

6. Now run the kernel debugger on the live system (either WinDbg in local kernel debugging mode or LiveKd if you are on Windows 2000), display the process list with !process, and find the recently created process running Cmd.exe. Then display the process block by using !process <process ID>, find the address of the job object, and finally display the job object with the !job command. Here's some partial debugger output of these commands on a live system:

   lkd> !process 0 0 **** NT ACTIVE PROCESS DUMP ****     .     . PROCESS 8567b758  SessionId: 0  Cid: 0fc4    Peb: 7ffdf000   ParentCid: 00b0     DirBase: 1b3fb000  ObjectTable: e18dd7d0  HandleCount:  19.     Image:  cmd.exe PROCESS 856561a0  SessionId: 0 Cid: 0d70     Peb: 7ffdf000   ParentCid: 0fc4     DirBase: 2e341000  ObjectTable: e19437c8  HandleCount:  16.     Image:  notepad.exe lkd>!process  0fc4 Searchingfor  Process  withCid==fc4 PROCESS  8567b758    SessionId:  0  Cid:0fc4        Peb: 7ffdf000   ParentCid:00b0     DirBase:1b3fb000    ObjectTable: e18dd7d0    HandleCount:  19.     Image:  cmd.exe     BasePriority                       8     .     .     Job                                85557988 lkd>!job85557988 Job at 85557988   TotalPageFaultCount       0   TotalProcesses            2   ActiveProcesses           2   TotalTerminatedProcesses  0   LimitFlags                0   MinimumWorkingSetSize     0   MaximumWorkingSetSize     0   ActiveProcessLimit        0   PriorityClass             0   UIRestrictionsClass       0   SecurityLimitFlags        0   Token                     00000000

   
   

7. Finally, use the dt command to display the job object and notice the additional fields shown about the job:

   lkd> dt nt!_ejob85557988 nt!_EJOB    +0x000 Event            : _KEVENT    +0x010 JobLinks         : _LIST_ENTRY [0x805455c8-0x85797888]    +0x018 ProcessListHead  : _LIST_ENTRY [0x8567b8dc-0x85656324]    +0x020 JobLock          : _ERESOURCE    +0x058 TotalUserTime    : _LARGE_INTEGER 0x0    +0x060 TotalKernelTime  : _LARGE_INTEGER 0x0    +0x068 ThisPeriodTotalUserTime : _LARGE_INTEGER  0x0    +0x070 ThisPeriodTotalKernelTime : _LARGE_INTEGER 0x0    +0x078 TotalPageFaultCount : 0    +0x07c TotalProcesses   : 2    +0x080 ActiveProcesses  : 2    +0x084 TotalTerminatedProcesses : 0    +0x088 PerProcessUserTimeLimit : _LARGE_INTEGER 0x0    +0x090 PerJobUserTimeLimit : _LARGE_INTEGER 0x0    +0x098 LimitFlags       : 0    +0x09c MinimumWorkingSetSize : 0    +0x0a0 MaximumWorkingSetSize : 0    +0x0a4 ActiveProcessLimit : 0    +0x0a8 Affinity         : 0    +0x0ac PriorityClass    : 0''    +0x0b0 UIRestrictionsClass : 0    +0x0b4 SecurityLimitFlags : 0    +0x0b8 Token            : (null)    +0x0bc Filter           : (null)    +0x0c0 EndOfJobTimeAction : 0    +0x0c4 CompletionPort   : 0x8619d8c0    +0x0c8 CompletionKey    : (null)    +0x0cc SessionId        : 0    +0x0d0 SchedulingClass  : 5    +0x0d8 ReadOperationCount : 0    +0x0e0 WriteOperationCount : 0    +0x0e8 OtherOperationCount :0    +0x0f0 ReadTransferCount : 0    +0x0f8 WriteTransferCount : 0    +0x100 OtherTransferCount : 0    +0x108 IoInfo           : _IO_COUNTERS    +0x138 ProcessMemoryLimit : 0    +0x13c JobMemoryLimit   : 0    +0x140 PeakProcessMemoryUsed : 0x256    +0x144 PeakJobMemoryUsed : 0x1f6    +0x148 CurrentJobMemoryUsed : 0x1f6    +0x14c MemoryLimitsLock : _FAST_MUTEX    +0x16c JobSetLinks      : _LIST_ENTRY [0x85557af4 - 0x85557af4]    +0x174 MemberLevel      : 0    +0x178 JobFlags        :0