Runs: programming

You can both initiate run transitions, and perform work whenever a transition happens.

Transition types

There are 5 transition types:

Note the extra start aborted transition. This is used when a start transition is attempted, but a client returns an error. Clients are told that the start was aborted, so they can do any cleanup that they would normally do at the end of a run (e.g. turning off hardware, stopping any threads that were spawned etc).

Sequence ordering

Each client defines the sequencer order in which it should be told about the transition. These are integer numbers, and clients with lower numbers are told about the transition first. Different orders can be specified for the different transition types (e.g. a program could be the first one to be told about a run starting, and the last one to be told about it stopping).

Clients are able to report an error, for example to prevent a run from starting. Subsequent clients would then not be told about the transition.

If multiple clients have the same sequence number, they handle the transition at the same time (in parallel).

flowchart LR
  L["mlogger (200)"] --> A["frontend A (500)"]
  L --> B["frontend B (500)"]
  A --> C["frontend C (900)"]
  B --> C

Default transition sequence numbers

The default transition sequence numbers are shown in the table below. Note that the value for each frontend can be changed; 500 is just the default.

Initiating transitions from code

You can start/stop/pause/resume runs from code.

INT run_number = 0;
INT async_flag = TR_ASYNC | TR_MTHREAD;
char error[256] = {};
INT status = cm_transition(TR_START, run_number, error, sizeof(error), async_flag, 0);

client.start_run() #(1)!
client.stop_run()
client.pause_run()
client.resume_run()

Handling transitions

Registering a callback function

INT my_callback(INT run_number, char *error) {
  if (some_problem_detected) {
    snprintf(error, 255, "Couldn't start run due to ....");
    return FE_ERR_DRIVER;
  }

  printf("Run number %d is starting\n", run_number);
  return CM_SUCCESS;
}

// Later, in main function...
INT status = cm_register_transition(TR_START, my_callback, 500);

def my_callback(client, run_number): #(1)!
    if some_problem_detected:
        return (midas.FE_ERR_DRIVER, "Couldn't start run due to ....")

    print(f"Run number {run_number} is starting!")
    return midas.SUCCESS

# Later, in main function...
client.register_transition_callback(midas.TR_START, 500, my_callback)

Setting the sequence order

Although you specify the sequence order when you register the callback, you can later change it. This is useful if you are using a frontend framework, as the framework uses a value of 500 by default.

INT status = cm_set_transition_sequence(TR_START, 750);

client.set_transition_sequence(midas.TR_START, 750)

Multiple transition callbacks from one program

A program can register multiple callback functions for the same transition.

flowchart LR
    A["Pulser frontend:<br>pre-computation<br>(400)"] --> B["Some other frontend:<br>uses that info<br>(500)"]
    B --> C["Pulser frontend:<br>starts the hardware<br>(600)"]

status = cm_register_transition(midas.TR_START, callback_precompute, 400)
status = cm_register_transition(midas.TR_START, callback_start_hw, 600)

client.register_transition_callback(midas.TR_START, 400, callback_precompute)
client.register_transition_callback(midas.TR_START, 600, callback_start_hw)

Deferred transitions

Deferred transitions allow a frontend to delay a run transition until it has done more work. Other clients do not know that a transition has been requested until the "deferring" frontend completes its work.

The order of operations for a deferred transition is:

• A transition is requested
• The ODB flag /Runinfo/Requested transition is set, but other clients aren't told about the transition
• A callback function in the "deferring" client is called repeatedly
• When this function returns true, the transition proceeds as normal

Note that deferred transitions are skipped if using the "stop now" or "start now" commands in odbedit.

INT my_callback(INT transition, BOOL first) { //(1)!
  if (finished_doing_some_work) {
    return TRUE;
  }

  return FALSE;
}

// Later, in main function...
INT status = cm_register_deferred_transition(TR_STOP, my_callback);

// If you are NOT using the mfe frontend framework:
while (true) {
  status = cm_yield(1000);

  if (status == RPC_SHUTDOWN || status == SS_ABORT) {
    break;
  }

  status = cm_check_deferred_transition();
}

def my_callback(client, transition_type):
    if finished_doing_some_work:
        return True
    else:
        return False

# Later, in main function...
client.register_deferred_transition_callback(midas.TR_STOP, my_callback)

# If you are NOT using the midas.frontend framework:
while True:
    client.communicate(1000)
    client.check_deferred_transition()