windows-xp/Source/XPSP1/NT/base/cluster/resdll/genjob/dll/design.txt

Rough Design notes for Job Object Resource

Based on genapp, this resource will allow users to take advantage of job
objects on NT5. It provides for setting all the job object information via the
properties associated with the resource. Here's a breakdown of how the
different job info classes are utilized:

JobObjectAssociateCompletionPortInformation

    The genjob resdll uses a completion port to get notified about various
    events for a job object. The CompletionKey is a pointer to the genjob
    resource object. This facility is used mainly to log interesting genjob
    events to the cluster log. Nothing is exposed to the user. Receiving
    JOB_OBJECT_MSG_ACTIVE_PROCESS_ZERO causes the offline event for the
    resource to be signalled.

JobObjectBasicLimitInformation

    Each member (except for LimitFlags and Affinity) in this class will
    correspond to a resource property. Affinity poses a challenge since it is
    possible to have UP/MP nodes in the cluster. I'm not sure how to handle
    this right now. Initially, we won't support this
    feature. JOB_OBJECT_LIMIT_DIE_ON_UNHANDLED_EXCEPTION will be set to avoid
    having hard popups from the system if a process terminates due to a
    fault. This will allow the job to fail over to the other side. Check boxes
    will be present to support the child process breakaway features. These
    properties can be modified while the resource is online.

JobObjectBasicUIRestrictions

    basically, one check box per flag for this sheet.

JobObjectEndOfJobTimeInformation

    Radio button indicating which option is enforce.

JobObjectExtendedLimitInformation

    more edit boxes for the limits added by this class    

JobObjectSecurityLimitInformation

    This is potentially a difficult class to get working. It involves token
    handles, privileges and groups to be specified. There would be additional
    pages that would display groups and privileges. The main page would
    capture a domain account (including password) so a token handle could be
    generated under which to run the process. Hopefully, there are canned UI
    calls to display this type of info. The resdll will need to turn on assign
    primary token before supporting the JobToken field.

Resource code

Open

    same as genapp

Online

    A critsec protects the creation of the completion port. A count of online
    resources is maintained: incremented during online and dec'ed during
    offline, it indicates when the completion port should be
    created/deleted. The final resource offline closes the port handle.

    Calls CreateJobObject, SetInformationJobObject (based on the properties),
    CreateProcess, and finally AssociateProcessToJobObject. Resource structure
    needs to be complete enough such that the comp. port handler can access
    the member without accvio'ing. This shouldn't be an issue since we
    probably just use the resource handle for logging. An event is used to
    signal resmon when the final process exits. The job handle maintains
    signal state but it is used to indicate when other limits have been
    exceeded.

Offline

    calls TerminateJobObject (harsh but consistent with genapp). closes job
    obj handle. if last resource is taken offline, completion port giblets are
    closed as well.

Close

    same as genapp