


			CONDOR_STARTER INTRODUCTION


General
    This directory comprises the condor_starter.  The starter is
    implemented as a finite state machine, and that machine is
    documented by an idraw document "StateDiagram.idraw".  Note:
    idraw documents are postscript files augmented by structured
    comments.  You can send them directly to a postscript printer
    even if you don't have idraw.  The key for interpretation of
    symbols on the state diagram is in "Notes.idraw".  The state
    machine is implemented by tables which are fed into a "state
    machine driver".  All the tables for the condor_starter are defined
    in "starter.h".

State Machine Driver
    This driver is implemented by "fsa.C".  It is quite generic, and
    could be initialized with a different set of tables to accomplish
    some completely different task.  The assumptions of the state
    machine driver are as follows:

    1. The machine is initialized with the following items (explained
       below)
	    1. State Table
	    2. Transition Table
	    3. List of signals
	    4. Identifier of the starting state
	    5. Identifier of the ending state

	    In addition the driver will expect 4 global name tables
	    1. Names of the states
	    2. Names of the events
	    3. Names of functions associated with states
	    4. Names of functions associated with transitions

    2. There is a pre-defined set of states represented by an enumeration.
    The driver itself doesn't need to be compiled with the enumeration
    because it looks at the states simply as integers.

    3. There is a pre-defined set of events, also represented by an
    enumeration.  Again, the driver need not be compiled with this
    enumeration since it looks at the events only as integers.

    4. Some events my be asynchronous and arrive in the form
    of POSIX signals.  In this case, it is assumed that the integer
    encoding the event and the signal representing the event are
    the same.  Such signals may be generated either internally, or
    sent from another process.  An example of useful internal generation
    of signals would be the user of SIGALRM for timers.

    5. Both states and transitions may have actions associated with
    them.  Those actions will be represented in the tables as pointers
    to functions.  Actions associated with states are expected to
    return an event which encodes the outcome of the action.  The event
    returned will determine which transition is taken out of the state.
    If there is only one transition out of a particular state, its
    associated function may return the DEFAULT event.  This special
    event must be encoded as "-1".  Functions associated with transitions
    should return void.

    6. Some states may want to accept asynchronous events, while others
    will not.  Each state has this attribute encoded in the state
    table.  Signals representing events will be blocked while executing
    in those states which don't want asynchronous events.  A state
    must either block all asynchronous events or none.  Events can
    be ignored by setting up a transition which returns to the
    starting state and has no associated function.

    7. Actions to be taken after an asynchronous event are encoded
    in the transition table.  If a function pointer is provided,
    that function will be called upon delivery of the event.  After
    the function completes, one of two actions will be taken.  Either
    a transition to another state, or a return to the current state, as dictated 
	by the transition table.  In the latter case, this is handled like an interrupt, i.e.
    we return to where we left off in the current state, not at the
    beginning.
	[Change 9/95: A transition function can now return must return an int with
	a value of 0 or of -2.  A return of 0 means follow what the transition
	table dictates, i.e. same as before.  A return of -2 means "abort the transition
	function", and return like an interrupt return - Todd].

    8. The programmer is free to choose which POSIX signals encode
    asynchronous events.  A list must be given to the state machine
    driver at initialization time.  The state machine driver blocks
    and unblocks the listed signals as needed during execution of
    the state machine.  Those signals will be left blocked when the
    state machine returns.  Also, note that the state machine driver
    will install its own handler for these signals during the execution
    of the machine.  During this time the programmer can only deal with
    those signals by associating them with transitions and transition
    functions.  The driver will reset the previous signal handlers 
    before returning from the machine.

Testing
    The condor_starter consists of about 10 states, 15 events,
    and 45 transitions.  Testing requires running of actual jobs,
    and generation of events in various stages of the running
    of those jobs.  The program "test_it" is designed to facilitate
    this task.  You must start it up with the process id of a
    condor starter on the command line, then it provides a menu
    of "events" to be sent to the starter.  A partial list of
    events which should be tried at various points in execution,
    and expected actions the condor_starter should take is included
    in "Notes.testing".
