EVENTS

Events are used to synchronize the operations of CSIM processes. An event consists of a state variable and two queues of processes waiting for the event to "happen". One of these queues is for processes which have executed a wait statement and one is for processes which have executed a queue statement. When the event "happens", all of the "waiting" processes and ONE of the "queued" processes are allowed to proceed. An event happens when a process (obviously one which is not waiting somewhere) sets the event to the occurred state. An event is automatically reset to the non-occurred state when all of the processes at the event which can proceed have done so. An event set is an array of events. A process can wait (or queue) for any event in an event_set to "happen". In addition, a process can specify a time-out interval, so that it will not wait more than a specified amount of time to pass before it proceeds (a returned status lets the process know whether the event occurred or the time-out expired).

Declaring and Initializing Events

To declare an event or set of events:
EVENT ev;
EVENT array[n];
Where:

  • ev - is the variable name representing the event (type EVENT)
  • array - is the variable name representing the set of events (array of type EVENT)
  • n - is the number of events in the event set (type long)
    Notes:
  • An EVENT must be initialized via the event, global_event, or event_set statement before it can be used in any other statement.

    To initialize an event or set of events:
    ev = event("name");
    ev = global_event(“name”);
    event_set(array, "name", n);
    Where:

  • ev - is the variable name representing the event (type EVENT)
  • array - is the variable name representing the set of events (array of type EVENT)
  • name - is the name of the event or set of events (quoted string or type char*)
  • n - is the number of events in the event set (type long)
    Notes:
  • An event declared and initialized in the sim (first) process is globally accessible.
  • An event declared and initialized in any other process is assumed to be local to the declaring process. To override this assumption and make such an event accessible globally, use the global_event statement.
  • An event set is globally accessible only if it is declared and initialized in the sim (first) process.
  • Local events can be passed as parameters to other processes.
  • Local events are deleted when the declaring process terminates.
  • All events are initialized to the not occurred state.
  • The i-th block in an event set is named "name[i]".
  • The pointer to the i-th event is stored at array[i].
  • The events in the set are indexed 0 through n-1.
  • name is used only for output (status, traces).

    To change the name of an event:
    set_name_event(ev,” name”);
    Where:

  • ev - is the event or event set whose name is to be changed (type EVENT)
  • name - is the new name for the event or event set (quoted string or type char*)
    Notes:
  • name is used only for output (status, traces).

    Deleting Events

    To delete an event or an event set:
    delete_event(ev);
    delete_event_set(array);
    Where:

  • ev - is the event to be deleted (type EVENT)
  • array - is the event set to be deleted (array of type EVENT)
    Notes:
  • If an event is local, only the process that created the event can delete it.

    Using Events

    To wait for an event to occur:
    wait(ev);
    Where

  • ev - is the event that the process needs to wait for (type EVENT)
    Notes:
  • If the event has already occurred (it is in the occurred state), the process continues to execute and the event is set to the not occurred state.
  • If the event has not occurred (it is in the not occurred state), the process is suspended and placed on a queue of processes waiting for the event to happen. When some other process does a set operation on the event, all of the waiting processes are allowed to continue processing (it is possible for several processes to be waiting for the occurrence of the same event). When all waiting processes have been reactivated, the event will be once again placed in the not occurred state.

    To wait for any event in an event set to occur:
    j = wait_any(array);
    Where:

  • j - is the array index of the event that actually occurred (type long)
  • array - is the event set in which any event that occurs will allow the process to continue (array of type EVENT)
    Notes:
  • When multiple events in the set are in the occurred state, the lowest numbered event is the one recognized by the next waiting process.
  • All processes which are waiting at the set are triggered by the next event which occurs, and these processes all receive the same index value (function value).
  • When an event in the set is recognized (causes a process to continue by virtue of its having occurred), it is automatically returned to the not occurred state.

    To wait for an event to occur, but only if it happens within a specified time:
    result = timed_wait(ev, time);
    Where:

  • result - is a returned indication of whether the event occurred (type long):
  • EVENT_OCCURRED if the event occurred
  • TIMED_OUT if the time limit expired
  • ev - is the event for which this process is waiting (type EVENT)
  • time - is the maximum amount of time that the process is willing to wait for the event to occur (type double)
    Notes:
  • The process must check the returned value (result) to determine whether the event occurred.

    To wait until there are no active processes:
    wait(event_list_empty);
    Notes:

  • This will occur when either:
  • All other processes have left the system (terminated)
  • All other processes are waiting (e.g. for a facility)

    To wait for an event to occur and for other processes to respond to it before proceeding:
    queue(ev);
    Where

  • ev - is the event that the process needs to wait for (type EVENT)
    Notes:
  • This is similar to wait(ev) except only one queued process is allowed to resume.
  • The queued process of highest priority (first to arrive in case of a tie) is restarted when the event occurs. All other queued processes remain queued (until subsequent occurrences of the event).
  • When there are both queued and waiting processes at an event, all of the waiting processes plus one queued process (if any) are reactivated.

    To queue on any event in an event set:
    j = queue_any(array);
    Where:

  • j - is the array index of the event that actually occurred (type long)
  • array - is the event set in which any event that occurs will allow the process to continue, assuming that it is at the top of the queue (array of type EVENT)
    Notes:
  • When multiple events in the set are in the occurred state, the lowest numbered event is the one recognized by the next waiting process.
  • Only one process on the queue is triggered by the next event which occurs. All others must wait for a subsequent occurrence of an event in the event set.
  • When an event in the set is recognized (causes a process to continue by virtue of its having occurred), it is automatically returned to the not occurred state.

    To queue, waiting for an event to occur, but only wait for a specified time:
    result = timed_queue(ev, time);
    Where:

  • result - is a returned indication of whether the event occurred (type long):
  • EVENT_OCCURRED if the event occurred
  • TIMED_OUT if the time limit expired
  • ev - is the event for which this process is waiting (type EVENT)
  • time - is the maximum amount of time that the process is willing to wait on the event queue (type double)
    Notes:
  • The process must check the returned value (result) to determine whether the event occurred.

    To indicate that an event has occurred:
    set(ev);
    Where

  • ev - is the event that is to be set to the occurred state (type EVENT)
    Notes:
  • When this statement is executed, all waiting processes and one queued process will be reactivated.
  • If there are no waiting or queued processes, the event will be in the occurred state after the set statement executes.
  • If there are waiting or queued processes, the event will be in the not occurred state after the set statement executes (since the event’s occurrence was recognized by a process).

    To set an event to the not occurred state:
    clear(ev);
    Where

  • ev - is the event that is to be set to the not occurred state (type EVENT)

    Retrieving Event-Related Information

    These functions each return a statistic which describes some aspect of the usage of the specified event. The type of the returned value for each of these functions is as indicated. The syntax conventions for these statements are as follows:
  • ev- is the event about which information is requested. It must be type EVENT.
  • n - is a returned value of type long.

    Retrieving Event Status Information> 

    Statement			Returned Value

    
n = wait_cnt(ev);		number of processes waiting for event ev
n = queue_cnt(ev);		number of processes queued for event ev
n = event_qlen(ev);		sum of the number of processes waiting for event ev and
					the number queued for event ev
n = state(ev);			state of event ev:
    
				    OCC if the event is in the occurred state
				    NOT_OCC if the event is in the not occurred state

    Reporting Event Status

    To print the status of each event in the model:
    status_events();
    Notes:

  • This report lists each event along with:
  • Its state
  • Number of processes waiting for it
  • Number of processes queued on it
  • The name and id of each process waiting for it
  • The name and id of each process queued on it
  • This report will list several “internal” events (not defined by the user). The person looking at the status report should ignore these.
  • The report will be written to the default output location or to that specified by set_output_file