Creating lists

You can create lists within, and for use with, the internal data structures you create for the Scheduler. A list is essentially a group of entities maintained in a particular order. The order is defined when the list is created, but can be overridden for particular operations on a list. You can use a list as a holding place for an indeterminate number of entities (a boundless array) or to represent a queue within the scheduling model.

You must access a list through the use of a list pointer (pointer to a list), which you can obtain from one of these two places:

• The function csmkls to make a list with statistics.
• The macro CSMXLS to make a list without statistics.

Note that list pointers are not entity pointers, so lists cannot be placed in other lists. However, an entity data structure can contain one or more list pointers, and that entity can then be placed in a list.

You can choose a FIFO or a LIFO ordering for your list, or you can install a custom function to order your list. You can do this through the arguments on the function csmkls and the macro CSMXLS, as documented in the header file factor.h Observe that the arguments of both csmkls and CSMXLS include an ordering type and a pointer to an ordering function. The ordering type may be one of the following:

Type	Description
CSFIFO	The list is maintained in first-in-first-out (FIFO) order. New entities are inserted at the end of the list.
CSLIFO	The list is maintained in last-in-first-out (LIFO) order. New entities are inserted at the beginning of the list.
CSORDF	The list is ordered based on a user-defined ordering function, with FIFO ordering used in the case of ties.
CSORDL	The list is ordered based on a user-defined ordering function, with LIFO ordering used in the case of ties.

For CSFIFO and CSLIFO, you need not install an ordering function and you must use NULL for the pointer to the ordering function. For CSORDF and CSORDL, you should use the pointer to your custom ordering function for this argument.

List ordering functions provide a criterion for comparing two entities on the list. The system inserts entities based on the criterion given in the function. The list ordering function is called automatically by the system each time a new entity is inserted in the list.

Your custom list ordering function must accept two arguments, both of which are pointers to the entities of the type which the list is to hold. Your function should obtain a value for each of the two entities based on some attribute of the entity. Your function should return an integer indicating which entity should be placed ahead of the other in the list as follows:

• If entity1 should be placed ahead of entity2, then return a value < 0.
• If entity1 should be placed after of entity2, then return a value > 0.
• If the entity1 and entity2 are tied, then return 0.

The list is maintained in ascending order based on the criterion in the ordering function. To provide a descending ordering, simply reverse the sign of the return values (i.e., multiply by –1).

The following example is a function to order a list first in alphabetical order based on job ID and second in numerical order based on load ID:

int compfun(lt1, lt2)
LOADTAG *lt1, *lt2;
{
   int ord;

   /* Check whether jobs are identical. */
   ord = strcmp(lt1->ldp->loordp->orid,
         lt2->ldp->loordp->orid);

   /* If not identical, return the ordering given by strcmp. */
   if (ord != 0)
   {
     return(ord);
   }

   /* If identical, return the ordering by load. */
   return(lt1->ldp->loid - lt2->ldp->loid);
}

The relationship returned by the standard C function strcmp has the same convention as the list ordering function. If the orders are not identical, the comparison of the IDs may be returned as is. If the orders are identical, further comparison must be made on the basis of their load IDs. Since the load IDs are integer, subtracting the second load ID from the first results in the required comparison return value. The ordering code on a list can be changed using the function setosq. This is useful for request lists that will be reordered by the selection rule, i.e., Dynamic Slack. The list ordering can be changed to CSFIFO which eliminates searching when putting entities into the list.