| Platform SDK: DLLs, Processes, and Threads |
The JOBOBJECT_ASSOCIATE_COMPLETION_PORT structure contains information used to associate a completion port with a job. You can associate one completion port with a job. There is no way to terminate the association and no way to associate a different port with the job.
typedef struct _JOBOBJECT_ASSOCIATE_COMPLETION_PORT {
PVOID CompletionKey;
HANDLE CompletionPort;
} JOBOBJECT_ASSOCIATE_COMPLETION_PORT, PJOBOBJECT_ASSOCIATE_COMPLETION_PORT;
The job sends messages to the completion port when certain events occur. All messages are sent directly from the job as if the job had called the PostQueuedCompletionStatus function. A thread monitoring the completion port using the GetQueuedCompletionStatus function must pick up the messages. The thread receives information in the GetQueuedCompletionStatus parameters shown in the following table.
| Parameter | Information Received |
|---|---|
| lpCompletionKey | The value specified in CompletionKey during the completion-port association. If a completion port is associated with multiple jobs, CompletionKey should help the caller determine which completion port is sending a message. |
| lpOverlapped | Message-specific value. For more information, see the following table of message identifiers. |
| LpNumberOfBytesTransfered | The message identifier that indicates which job-related event occurred. For more information, see the following table of message identifiers. |
The following messages can be sent to the completion port.
| Message Identifier | Description |
|---|---|
| JOB_OBJECT_MSG_END_OF_JOB_TIME | Indicates that the JOB_OBJECT_POST_AT_END_OF_JOB option is in effect and the end-of-job time limit has been reached. Upon posting this message, the time limit is canceled and the job's processes can continue to run.
The value of lpOverlapped is NULL. |
| JOB_OBJECT_MSG_END_OF_PROCESS_TIME | Indicates that a process has exceeded a per-process time limit. The system sends this message after the process termination has been requested.
The value of lpOverlapped is the identifier of the process that exceeded its limit. |
| JOB_OBJECT_MSG_ACTIVE_PROCESS_LIMIT | Indicates that the active process limit has been exceeded.
The value of lpOverlapped is NULL. |
| JOB_OBJECT_MSG_ACTIVE_PROCESS_ZERO | Indicates that the active process count has been decremented to 0. For example, if the job currently has two active processes, the system sends this message after they both terminate.
The value of lpOverlapped is NULL. |
| JOB_OBJECT_MSG_NEW_PROCESS | Indicates that a process has been added to the job. Processes added to a job at the time a completion port is associated are also reported.
The value of lpOverlapped is the identifier of the process added to the job. |
| JOB_OBJECT_MSG_EXIT_PROCESS | Indicates that a process associated with the job has exited.
The value of lpOverlapped is the identifier of the exiting process. |
| JOB_OBJECT_MSG_ABNORMAL_EXIT_PROCESS | Indicates that a process associated with the job exited with an exit code that indicates an abnormal exit (see the list following this table).
The value of lpOverlapped is the identifier of the exiting process. |
| JOB_OBJECT_MSG_PROCESS_MEMORY_LIMIT | Indicates that a process associated with the job has exceeded its memory limit (if one is in effect).
The value of lpOverlapped is the identifier of the process that has exceeded its limit. The system does not send this message if the process has not yet reported its process identifier. |
| JOB_OBJECT_MSG_JOB_MEMORY_LIMIT | Indicates that a process associated with the job caused the job to exceed the job-wide memory limit (if one is in effect).
The value of lpOverlapped specifies the identifier of the process that has attempted to exceed the limit. The system does not send this message if the process has not yet reported its process identifier. |
The following exit codes indicate an abnormal exit:
STATUS_ACCESS_VIOLATION
STATUS_ARRAY_BOUNDS_EXCEEDED
STATUS_BREAKPOINT
STATUS_CONTROL_C_EXIT
STATUS_DATATYPE_MISALIGNMENT
STATUS_FLOAT_DENORMAL_OPERAND
STATUS_FLOAT_DIVIDE_BY_ZERO
STATUS_FLOAT_INEXACT_RESULT
STATUS_FLOAT_INVALID_OPERATION
STATUS_FLOAT_MULTIPLE_FAULTS
STATUS_FLOAT_MULTIPLE_TRAPS
STATUS_FLOAT_OVERFLOW
STATUS_FLOAT_STACK_CHECK
STATUS_FLOAT_UNDERFLOW
STATUS_GUARD_PAGE_VIOLATION
STATUS_ILLEGAL_INSTRUCTION
STATUS_IN_PAGE_ERROR
STATUS_INVALID_DISPOSITION
STATUS_INTEGER_DIVIDE_BY_ZERO
STATUS_INTEGER_OVERFLOW
STATUS_NONCONTINUABLE_EXCEPTION
STATUS_PRIVILEGED_INSTRUCTION
STATUS_REG_NAT_CONSUMPTION
STATUS_SINGLE_STEP
STATUS_STACK_OVERFLOW
You must be cautious when using the JOB_OBJECT_MSG_NEW_PROCESS and JOB_OBJECT_MSG_EXIT_PROCESS messages, as race conditions may occur. For instance, if processes are actively starting and exiting within a job, and you are in the process of assigning a completion port to the job, you may miss messages for processes whose states change during the association of the completion port. For this reason, it is best to associate a completion port with a job when the job is inactive.
Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Winnt.h; include Windows.h.
Processes and Threads Overview, Process and Thread Structures, PostQueuedCompletionStatus, QueryInformationJobObject, SetInformationJobObject