Actual source code: logstate.c

      1: #include <petsc/private/logimpl.h>

      3: /*@
      4:   PetscLogStateCreate - Create a logging state.

      6:   Not collective

      8:   Output Parameters:
      9: . state - a `PetscLogState`

     11:   Level: developer

     13:   Note:
     14:   Most users will not need to create a `PetscLogState`.  The global state `PetscLogState()`
     15:   is created in `PetscInitialize()`.

     17: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateDestroy()`
     18: @*/
     19: PetscErrorCode PetscLogStateCreate(PetscLogState *state)
     20: {
     21:   PetscInt      num_entries, max_events, max_stages;
     22:   PetscLogState s;

     24:   PetscFunctionBegin;
     25:   PetscCall(PetscNew(state));
     26:   s = *state;
     27:   PetscCall(PetscLogRegistryCreate(&s->registry));
     28:   PetscCall(PetscIntStackCreate(&s->stage_stack));
     29:   PetscCall(PetscLogRegistryGetNumEvents(s->registry, NULL, &max_events));
     30:   PetscCall(PetscLogRegistryGetNumStages(s->registry, NULL, &max_stages));

     32:   s->bt_num_events = max_events + 1; // one extra column for default stage activity
     33:   s->bt_num_stages = max_stages;
     34:   num_entries      = s->bt_num_events * s->bt_num_stages;
     35:   PetscCall(PetscBTCreate(num_entries, &s->active));
     36:   s->current_stage = -1;
     37:   s->refct         = 1;
     38:   PetscFunctionReturn(PETSC_SUCCESS);
     39: }

     41: /*@
     42:   PetscLogStateDestroy - Destroy a logging state.

     44:   Not collective

     46:   Input Parameters:
     47: . state - a `PetscLogState`

     49:   Level: developer

     51:   Note:
     52:   Most users will not need to destroy a `PetscLogState`.  The global state `PetscLogState()`
     53:   is destroyed in `PetscFinalize()`.

     55: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateCreate()`
     56: @*/
     57: PetscErrorCode PetscLogStateDestroy(PetscLogState *state)
     58: {
     59:   PetscLogState s;

     61:   PetscFunctionBegin;
     62:   s      = *state;
     63:   *state = NULL;
     64:   if (s == NULL || --(s->refct) > 0) PetscFunctionReturn(PETSC_SUCCESS);
     65:   PetscCall(PetscLogRegistryDestroy(s->registry));
     66:   PetscCall(PetscIntStackDestroy(s->stage_stack));
     67:   PetscCall(PetscBTDestroy(&s->active));
     68:   PetscCall(PetscFree(s));
     69:   PetscFunctionReturn(PETSC_SUCCESS);
     70: }

     72: /*@
     73:   PetscLogStateStagePush - Start a new logging stage.

     75:   Not collective

     77:   Input Parameters:
     78: + state - a `PetscLogState`
     79: - stage - a registered `PetscLogStage`

     81:   Level: developer

     83:   Note:
     84:   This is called for the global state (`PetscLogGetState()`) in `PetscLogStagePush()`.

     86: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateStageRegister()`, `PetscLogStateStagePop()`, `PetscLogStateGetCurrentStage()`
     87: @*/
     88: PetscErrorCode PetscLogStateStagePush(PetscLogState state, PetscLogStage stage)
     89: {
     90:   PetscFunctionBegin;
     91:   if (PetscDefined(USE_DEBUG)) {
     92:     PetscInt num_stages;
     93:     PetscCall(PetscLogRegistryGetNumStages(state->registry, &num_stages, NULL));
     94:     PetscCheck(stage >= 0 && stage < num_stages, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Invalid stage %d not in [0,%d)", stage, (int)num_stages);
     95:   }
     96:   PetscCall(PetscIntStackPush(state->stage_stack, stage));
     97:   state->current_stage = stage;
     98:   PetscFunctionReturn(PETSC_SUCCESS);
     99: }

    101: /*@
    102:   PetscLogStateStagePop - End a running logging stage.

    104:   Not collective

    106:   Input Parameter:
    107: . state - a `PetscLogState`

    109:   Level: developer

    111:   Note:
    112:   This is called for the global state (`PetscLogGetState()`) in `PetscLogStagePush()`.

    114: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateStageRegister()`, `PetscLogStateStagePush()`, `PetscLogStateGetCurrentStage()`
    115: @*/
    116: PetscErrorCode PetscLogStateStagePop(PetscLogState state)
    117: {
    118:   int       curStage;
    119:   PetscBool empty;

    121:   PetscFunctionBegin;
    122:   PetscCall(PetscIntStackPop(state->stage_stack, &curStage));
    123:   PetscCall(PetscIntStackEmpty(state->stage_stack, &empty));
    124:   if (!empty) {
    125:     PetscCall(PetscIntStackTop(state->stage_stack, &state->current_stage));
    126:   } else state->current_stage = -1;
    127:   PetscFunctionReturn(PETSC_SUCCESS);
    128: }

    130: /*@
    131:   PetscLogStateGetCurrentStage - Get the last stage that was started

    133:   Not collective

    135:   Input Parameter:
    136: . state - a `PetscLogState`

    138:   Output Parameter:
    139: . current - the last `PetscLogStage` started with `PetscLogStateStagePop()`

    141:   Level: developer

    143:   Note:
    144:   This is called for the global state (`PetscLogGetState()`) in `PetscLogGetCurrentStage()`.

    146: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateStageRegister()`, `PetscLogStateStagePush()`, `PetscLogStateStagePop()`
    147: @*/
    148: PetscErrorCode PetscLogStateGetCurrentStage(PetscLogState state, PetscLogStage *current)
    149: {
    150:   PetscFunctionBegin;
    151:   *current = state->current_stage;
    152:   PetscFunctionReturn(PETSC_SUCCESS);
    153: }

    155: static PetscErrorCode PetscLogStateResize(PetscLogState state)
    156: {
    157:   PetscBT  active_new;
    158:   PetscInt new_num_events;
    159:   PetscInt new_num_stages;

    161:   PetscFunctionBegin;
    162:   PetscCall(PetscLogRegistryGetNumEvents(state->registry, NULL, &new_num_events));
    163:   new_num_events++;
    164:   PetscCall(PetscLogRegistryGetNumStages(state->registry, NULL, &new_num_stages));

    166:   if (state->bt_num_events == new_num_events && state->bt_num_stages == new_num_stages) PetscFunctionReturn(PETSC_SUCCESS);
    167:   PetscCheck((new_num_stages % PETSC_BITS_PER_BYTE) == 0, PETSC_COMM_SELF, PETSC_ERR_ARG_INCOMP, "new number of stages must be multiple of %d", PETSC_BITS_PER_BYTE);
    168:   PetscCall(PetscBTCreate(new_num_events * new_num_stages, &active_new));
    169:   if (new_num_stages == state->bt_num_stages) {
    170:     // single memcpy
    171:     size_t num_chars = (state->bt_num_stages * state->bt_num_events) / PETSC_BITS_PER_BYTE;

    173:     PetscCall(PetscMemcpy(active_new, state->active, num_chars));
    174:   } else {
    175:     size_t num_chars_old = state->bt_num_stages / PETSC_BITS_PER_BYTE;
    176:     size_t num_chars_new = new_num_stages / PETSC_BITS_PER_BYTE;

    178:     for (PetscInt i = 0; i < state->bt_num_events; i++) { PetscCall(PetscMemcpy(&active_new[i * num_chars_new], &state->active[i * num_chars_old], num_chars_old)); }
    179:   }
    180:   PetscCall(PetscBTDestroy(&state->active));
    181:   state->active        = active_new;
    182:   state->bt_num_events = new_num_events;
    183:   state->bt_num_stages = new_num_stages;
    184:   PetscFunctionReturn(PETSC_SUCCESS);
    185: }

    187: /*@
    188:   PetscLogStateStageRegister - Register a new stage with a logging state

    190:   Not collective

    192:   Input Parameters:
    193: + state - a `PetscLogState`
    194: - sname - a unique name

    196:   Output Parameter:
    197: . stage - the identifier for the registered stage

    199:   Level: developer

    201:   Note:
    202:   This is called for the global state (`PetscLogGetState()`) in `PetscLogStageRegister()`.

    204: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateStagePush()`, `PetscLogStateStagePop()`
    205: @*/
    206: PetscErrorCode PetscLogStateStageRegister(PetscLogState state, const char sname[], PetscLogStage *stage)
    207: {
    208:   PetscInt s;

    210:   PetscFunctionBegin;
    211:   PetscCall(PetscLogRegistryStageRegister(state->registry, sname, stage));
    212:   PetscCall(PetscLogStateResize(state));
    213:   s = *stage;
    214:   PetscCall(PetscBTSet(state->active, s)); // stages are by default active
    215:   for (PetscInt e = 1; e < state->bt_num_events; e++) {
    216:     // copy "Main Stage" activities
    217:     if (PetscBTLookup(state->active, 0 + e * state->bt_num_stages)) {
    218:       PetscCall(PetscBTSet(state->active, s + e * state->bt_num_stages));
    219:     } else {
    220:       PetscCall(PetscBTClear(state->active, s + e * state->bt_num_stages));
    221:     }
    222:   }
    223:   PetscFunctionReturn(PETSC_SUCCESS);
    224: }

    226: /*@
    227:   PetscLogStateEventRegister - Register a new event with a logging state

    229:   Not collective

    231:   Input Parameters:
    232: + state - a `PetscLogState`
    233: . sname - a unique name
    234: - id    - the `PetscClassId` for the type of object most closely associated with this event

    236:   Output Parameter:
    237: . event - the identifier for the registered event

    239:   Level: developer

    241:   Note:
    242:   This is called for the global state (`PetscLogGetState()`) in `PetscLogEventRegister()`.

    244: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStageRegister()`
    245: @*/
    246: PetscErrorCode PetscLogStateEventRegister(PetscLogState state, const char sname[], PetscClassId id, PetscLogEvent *event)
    247: {
    248:   PetscInt e;

    250:   PetscFunctionBegin;
    251:   *event = PETSC_DECIDE;
    252:   PetscCall(PetscLogRegistryGetEventFromName(state->registry, sname, event));
    253:   if (*event > 0) PetscFunctionReturn(PETSC_SUCCESS);
    254:   PetscCall(PetscLogRegistryEventRegister(state->registry, sname, id, event));
    255:   PetscCall(PetscLogStateResize(state));
    256:   e = *event;
    257:   for (PetscInt s = 0; s < state->bt_num_stages; s++) PetscCall(PetscBTSet(state->active, s + (e + 1) * state->bt_num_stages)); // events are by default active
    258:   PetscFunctionReturn(PETSC_SUCCESS);
    259: }

    261: /*@
    262:   PetscLogStateEventSetCollective - Set the collective nature of a logging event

    264:   Logically collective

    266:   Input Parameters:
    267: + state      - a `PetscLogState`
    268: . event      - a registered `PetscLogEvent`
    269: - collective - if `PETSC_TRUE`, MPI processes synchronize during this event, and `PetscLogHandlerEventSync()` can be used to help measure the delays between when the processes begin the event

    271:   Level: developer

    273:   Note:
    274:   This is called for the global state (`PetscLogGetState()`) in `PetscLogEventSetCollective()`.

    276: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogEventRegister()`
    277: @*/
    278: PetscErrorCode PetscLogStateEventSetCollective(PetscLogState state, PetscLogEvent event, PetscBool collective)
    279: {
    280:   PetscFunctionBegin;
    281:   PetscCall(PetscLogRegistryEventSetCollective(state->registry, event, collective));
    282:   PetscFunctionReturn(PETSC_SUCCESS);
    283: }

    285: /*@
    286:   PetscLogStateStageSetActive - Mark a stage as active or inactive.

    288:   Not collective

    290:   Input Parameters:
    291: + state    - a `PetscLogState`
    292: . stage    - a registered `PetscLogStage`
    293: - isActive - if `PETSC_FALSE`, `PetscLogStateEventGetActive()` will return `PETSC_FALSE` for all events during this stage

    295:   Level: developer

    297:   Note:
    298:   This is called for the global state (`PetscLogGetState()`) in `PetscLogStageSetActive()`

    300: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateEventSetActive()`
    301: @*/
    302: PetscErrorCode PetscLogStateStageSetActive(PetscLogState state, PetscLogStage stage, PetscBool isActive)
    303: {
    304:   PetscFunctionBegin;
    305:   PetscCheck(stage >= 0 && stage < state->bt_num_stages, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Invalid stage %d should be in [0,%d)", stage, state->bt_num_stages);
    306:   if (isActive) {
    307:     for (PetscInt e = 0; e < state->bt_num_events; e++) { PetscCall(PetscBTSet(state->active, stage + e * state->bt_num_stages)); }
    308:   } else {
    309:     for (PetscInt e = 0; e < state->bt_num_events; e++) { PetscCall(PetscBTClear(state->active, stage + e * state->bt_num_stages)); }
    310:   }
    311:   PetscFunctionReturn(PETSC_SUCCESS);
    312: }

    314: /*@
    315:   PetscLogStateStageGetActive - Check if a logging stage is active or inactive.

    317:   Not collective

    319:   Input Parameters:
    320: + state - a `PetscLogState`
    321: - stage - a registered `PetscLogStage`

    323:   Output Parameter:
    324: . isActive - if `PETSC_FALSE`, the state should not send logging events to log handlers during this stage.

    326:   Level: developer

    328:   Note:
    329:   This is called for the global state (`PetscLogGetState()`) in `PetscLogStageGetActive()`.

    331: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStageSetActive()`, `PetscLogHandler`, `PetscLogHandlerStart()`, `PetscLogHandlerEventBegin()`, `PetscLogHandlerEventEnd()`
    332: @*/
    333: PetscErrorCode PetscLogStateStageGetActive(PetscLogState state, PetscLogStage stage, PetscBool *isActive)
    334: {
    335:   PetscFunctionBegin;
    336:   *isActive = PetscBTLookup(state->active, stage) ? PETSC_TRUE : PETSC_FALSE;
    337:   PetscFunctionReturn(PETSC_SUCCESS);
    338: }

    340: /*@
    341:   PetscLogStateEventSetActive - Set a logging event as active or inactive during a logging stage.

    343:   Not collective

    345:   Input Parameters:
    346: + state    - a `PetscLogState`
    347: . stage    - a registered `PetscLogStage`, or `PETSC_DEFAULT` for the current stage
    348: . event    - a registered `PetscLogEvent`
    349: - isActive - if `PETSC_FALSE`, `PetscLogStateEventGetActive()` will return `PETSC_FALSE` for this stage and this event

    351:   Level: developer

    353:   Note:
    354:   This is called for the global state (`PetscLogGetState()`) in `PetscLogEventActivate()` and `PetscLogEventDeactivate()`.

    356: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogEventGetActive()`, `PetscLogStateGetCurrentStage()`, `PetscLogEventSetActiveAll()`
    357: @*/
    358: PetscErrorCode PetscLogStateEventSetActive(PetscLogState state, PetscLogStage stage, PetscLogEvent event, PetscBool isActive)
    359: {
    360:   PetscFunctionBegin;
    361:   stage = (stage < 0) ? state->current_stage : stage;
    362:   PetscCheck(event >= 0 && event < state->bt_num_events, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Invalid event %d should be in [0,%d)", event, state->bt_num_events);
    363:   PetscCheck(stage >= 0 && stage < state->bt_num_stages, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Invalid stage %d should be in [0,%d)", stage, state->bt_num_stages);
    364:   PetscCall((isActive ? PetscBTSet : PetscBTClear)(state->active, state->current_stage + (event + 1) * state->bt_num_stages));
    365:   PetscFunctionReturn(PETSC_SUCCESS);
    366: }

    368: /*@
    369:   PetscLogStateEventSetActiveAll - Set logging event as active or inactive for all logging stages

    371:   Not collective

    373:   Input Parameters:
    374: + state    - a `PetscLogState`
    375: . event    - a registered `PetscLogEvent`
    376: - isActive - if `PETSC_FALSE`, `PetscLogStateEventGetActive()` will return `PETSC_FALSE` for all stages and all events

    378:   Level: developer

    380:   Note:
    381:   This is called for the global state (`PetscLogGetState()`) in `PetscLogEventSetActiveAll()`.

    383: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogEventGetActive()`
    384: @*/
    385: PetscErrorCode PetscLogStateEventSetActiveAll(PetscLogState state, PetscLogEvent event, PetscBool isActive)
    386: {
    387:   PetscFunctionBegin;
    388:   PetscCheck(event >= 0 && event < state->bt_num_events, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Invalid event %d should be in [0,%d)", event, state->bt_num_events);
    389:   for (int stage = 0; stage < state->bt_num_stages; stage++) { PetscCall((isActive ? PetscBTSet : PetscBTClear)(state->active, state->current_stage + (event + 1) * state->bt_num_stages)); }
    390:   PetscFunctionReturn(PETSC_SUCCESS);
    391: }

    393: /*@
    394:   PetscLogStateClassSetActive - Set logging events associated with an event as active or inactive during a logging stage.

    396:   Not collective

    398:   Input Parameters:
    399: + state    - a `PetscLogState`
    400: . stage    - a registered `PetscLogStage`, or `PETSC_DEFAULT` for the current stage
    401: . classid  - a `PetscClassId`
    402: - isActive - if `PETSC_FALSE`, `PetscLogStateEventGetActive()` will return
    403:              `PETSC_FALSE` for this stage and all events that were associated
    404:              with this class when they were registered (see
    405:              `PetscLogStateEventRegister()`).

    407:   Level: developer

    409:   Note:
    410:   This is called for the global state (`PetscLogGetState()`) in `PetscLogEventActivateClass()` and `PetscLogEventDeactivateClass()`.

    412: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogEventGetActive()`, `PetscLogStateEventSetActive()`
    413: @*/
    414: PetscErrorCode PetscLogStateClassSetActive(PetscLogState state, PetscLogStage stage, PetscClassId classid, PetscBool isActive)
    415: {
    416:   PetscInt num_events;

    418:   PetscFunctionBegin;
    419:   stage = stage < 0 ? state->current_stage : stage;
    420:   PetscCheck(stage >= 0 && stage < state->bt_num_stages, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Invalid stage %d should be in [0,%d)", stage, state->bt_num_stages);
    421:   PetscCall(PetscLogRegistryGetNumEvents(state->registry, &num_events, NULL));
    422:   for (PetscLogEvent e = 0; e < num_events; e++) {
    423:     PetscLogEventInfo event_info;
    424:     PetscCall(PetscLogRegistryEventGetInfo(state->registry, e, &event_info));
    425:     if (event_info.classid == classid) PetscCall((isActive ? PetscBTSet : PetscBTClear)(state->active, stage + (e + 1) * state->bt_num_stages));
    426:   }
    427:   PetscFunctionReturn(PETSC_SUCCESS);
    428: }

    430: /*@
    431:   PetscLogStateClassSetActiveAll - Set logging events associated with an event as active or inactive for all logging stages

    433:   Not collective

    435:   Input Parameters:
    436: + state    - a `PetscLogState`
    437: . classid  - a `PetscClassId`
    438: - isActive - if `PETSC_FALSE`, `PetscLogStateEventGetActive()` will return
    439:              `PETSC_FALSE` for all events that were associated with this class when they
    440:              were registered (see `PetscLogStateEventRegister()`).

    442:   Level: developer

    444:   Note:
    445:   This is called for the global state (`PetscLogGetState()`) in `PetscLogEventIncludeClass()` and `PetscLogEventExcludeClass()`.

    447: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogEventGetActive()`, `PetscLogStateClassSetActive()`
    448: @*/
    449: PetscErrorCode PetscLogStateClassSetActiveAll(PetscLogState state, PetscClassId classid, PetscBool isActive)
    450: {
    451:   PetscInt num_events, num_stages;

    453:   PetscFunctionBegin;
    454:   PetscCall(PetscLogRegistryGetNumEvents(state->registry, &num_events, NULL));
    455:   PetscCall(PetscLogRegistryGetNumStages(state->registry, &num_stages, NULL));
    456:   for (PetscLogEvent e = 0; e < num_events; e++) {
    457:     PetscLogEventInfo event_info;
    458:     PetscCall(PetscLogRegistryEventGetInfo(state->registry, e, &event_info));
    459:     if (event_info.classid == classid) {
    460:       for (PetscLogStage s = 0; s < num_stages; s++) { PetscCall((isActive ? PetscBTSet : PetscBTClear)(state->active, s + (e + 1) * state->bt_num_stages)); }
    461:     }
    462:   }
    463:   PetscFunctionReturn(PETSC_SUCCESS);
    464: }

    466: /*@
    467:   PetscLogStateEventGetActive - Check if a logging event is active or inactive during a logging stage.

    469:   Not collective

    471:   Input Parameters:
    472: + state - a `PetscLogState`
    473: . stage - a registered `PetscLogStage`, or `PETSC_DEFAULT` for the current stage
    474: - event - a registered `PetscLogEvent`

    476:   Output Parameter:
    477: . isActive - If `PETSC_FALSE`, log handlers should not be notified of the event's beginning or end.

    479:   Level: developer

    481:   Note:
    482:   This is called for the global state (`PetscLogGetState()`) in `PetscLogEventGetActive()`, where it has significance
    483:   for what information is sent to log handlers.

    485: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogEventGetActive()`, `PetscLogStateGetCurrentStage()`, `PetscLogHandler()`
    486: @*/
    487: PetscErrorCode PetscLogStateEventGetActive(PetscLogState state, PetscLogStage stage, PetscLogEvent event, PetscBool *isActive)
    488: {
    489:   PetscFunctionBegin;
    490:   stage = (stage < 0) ? state->current_stage : stage;
    491:   PetscCheck(event >= 0 && event < state->bt_num_events, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Invalid event %d should be in [0,%d)", event, state->bt_num_events);
    492:   PetscCheck(stage >= 0 && stage < state->bt_num_stages, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Invalid stage %d should be in [0,%d)", event, state->bt_num_stages);
    493:   *isActive = PetscLogStateStageEventIsActive(state, stage, event) ? PETSC_TRUE : PETSC_FALSE;
    494:   PetscFunctionReturn(PETSC_SUCCESS);
    495: }

    497: /*@
    498:   PetscLogStateGetEventFromName - Get a `PetscLogEvent` from the name it was registered with.

    500:   Not collective

    502:   Input Parameters:
    503: + state - a `PetscLogState`
    504: - name  - an event's name

    506:   Output Parameter:
    507: . event - the event's id

    509:   Level: developer

    511: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateEventRegister()`, `PetscLogStateEventGetInfo()`
    512: @*/
    513: PetscErrorCode PetscLogStateGetEventFromName(PetscLogState state, const char name[], PetscLogEvent *event)
    514: {
    515:   PetscFunctionBegin;
    516:   PetscCall(PetscLogRegistryGetEventFromName(state->registry, name, event));
    517:   PetscFunctionReturn(PETSC_SUCCESS);
    518: }

    520: /*@
    521:   PetscLogStateGetStageFromName - Get a `PetscLogStage` from the name it was registered with.

    523:   Not collective

    525:   Input Parameters:
    526: + state - a `PetscLogState`
    527: - name  - a stage's name

    529:   Output Parameter:
    530: . stage - the stage's id

    532:   Level: developer

    534: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateStageRegister()`, `PetscLogStateStageGetInfo()`
    535: @*/
    536: PetscErrorCode PetscLogStateGetStageFromName(PetscLogState state, const char name[], PetscLogStage *stage)
    537: {
    538:   PetscFunctionBegin;
    539:   PetscCall(PetscLogRegistryGetStageFromName(state->registry, name, stage));
    540:   PetscFunctionReturn(PETSC_SUCCESS);
    541: }

    543: /*@
    544:   PetscLogStateGetClassFromName - Get a `PetscLogClass` from the name of the class it was registered with.

    546:   Not collective

    548:   Input Parameters:
    549: + state - a `PetscLogState`
    550: - name  - the name string of the class

    552:   Output Parameter:
    553: . clss - the classes's logging id

    555:   Level: developer

    557: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateClassRegister()`, `PetscLogStateClassGetInfo()`
    558: @*/
    559: PetscErrorCode PetscLogStateGetClassFromName(PetscLogState state, const char name[], PetscLogClass *clss)
    560: {
    561:   PetscFunctionBegin;
    562:   PetscCall(PetscLogRegistryGetClassFromName(state->registry, name, clss));
    563:   PetscFunctionReturn(PETSC_SUCCESS);
    564: }

    566: /*@
    567:   PetscLogStateGetClassFromClassId - Get a `PetscLogClass` from the `PetscClassId` it was registered with.

    569:   Not collective

    571:   Input Parameters:
    572: + state   - a `PetscLogState`
    573: - classid - a `PetscClassId`

    575:   Output Parameter:
    576: . clss - the classes's logging id

    578:   Level: developer

    580: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateClassRegister()`, `PetscLogStateClassGetInfo()`
    581: @*/
    582: PetscErrorCode PetscLogStateGetClassFromClassId(PetscLogState state, PetscClassId classid, PetscLogClass *clss)
    583: {
    584:   PetscFunctionBegin;
    585:   PetscCall(PetscLogRegistryGetClassFromClassId(state->registry, classid, clss));
    586:   PetscFunctionReturn(PETSC_SUCCESS);
    587: }

    589: /*@
    590:   PetscLogStateGetNumEvents - Get the number of registered events in a logging state.

    592:   Not collective

    594:   Input Parameter:
    595: . state - a `PetscLogState`

    597:   Output Parameter:
    598: . numEvents - the number of registered `PetscLogEvent`s

    600:   Level: developer

    602: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateEventRegister()`
    603: @*/
    604: PetscErrorCode PetscLogStateGetNumEvents(PetscLogState state, PetscInt *numEvents)
    605: {
    606:   PetscFunctionBegin;
    607:   PetscCall(PetscLogRegistryGetNumEvents(state->registry, numEvents, NULL));
    608:   PetscFunctionReturn(PETSC_SUCCESS);
    609: }

    611: /*@
    612:   PetscLogStateGetNumStages - Get the number of registered stages in a logging state.

    614:   Not collective

    616:   Input Parameter:
    617: . state - a `PetscLogState`

    619:   Output Parameter:
    620: . numStages - the number of registered `PetscLogStage`s

    622:   Level: developer

    624: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateStageRegister()`
    625: @*/
    626: PetscErrorCode PetscLogStateGetNumStages(PetscLogState state, PetscInt *numStages)
    627: {
    628:   PetscFunctionBegin;
    629:   PetscCall(PetscLogRegistryGetNumStages(state->registry, numStages, NULL));
    630:   PetscFunctionReturn(PETSC_SUCCESS);
    631: }

    633: /*@
    634:   PetscLogStateGetNumClasses - Get the number of registered classes in a logging state.

    636:   Not collective

    638:   Input Parameter:
    639: . state - a `PetscLogState`

    641:   Output Parameter:
    642: . numClasses - the number of registered `PetscLogClass`s

    644:   Level: developer

    646: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateClassRegister()`
    647: @*/
    648: PetscErrorCode PetscLogStateGetNumClasses(PetscLogState state, PetscInt *numClasses)
    649: {
    650:   PetscFunctionBegin;
    651:   PetscCall(PetscLogRegistryGetNumClasses(state->registry, numClasses, NULL));
    652:   PetscFunctionReturn(PETSC_SUCCESS);
    653: }

    655: /*@
    656:   PetscLogStateEventGetInfo - Get the registration information of an event

    658:   Not collective

    660:   Input Parameters:
    661: + state - a `PetscLogState`
    662: - event - a registered `PetscLogEvent`

    664:   Output Parameter:
    665: . info - the `PetscLogEventInfo` of the event will be copied into info

    667:   Level: developer

    669: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateEventRegister()`, `PetscLogStateGetEventFromName()`
    670: @*/
    671: PetscErrorCode PetscLogStateEventGetInfo(PetscLogState state, PetscLogEvent event, PetscLogEventInfo *info)
    672: {
    673:   PetscFunctionBegin;
    674:   PetscCall(PetscLogRegistryEventGetInfo(state->registry, event, info));
    675:   PetscFunctionReturn(PETSC_SUCCESS);
    676: }

    678: /*@
    679:   PetscLogStateStageGetInfo - Get the registration information of an stage

    681:   Not collective

    683:   Input Parameters:
    684: + state - a `PetscLogState`
    685: - stage - a registered `PetscLogStage`

    687:   Output Parameter:
    688: . info - the `PetscLogStageInfo` of the stage will be copied into info

    690:   Level: developer

    692: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateStageRegister()`, `PetscLogStateGetStageFromName()`
    693: @*/
    694: PetscErrorCode PetscLogStateStageGetInfo(PetscLogState state, PetscLogStage stage, PetscLogStageInfo *info)
    695: {
    696:   PetscFunctionBegin;
    697:   PetscCall(PetscLogRegistryStageGetInfo(state->registry, stage, info));
    698:   PetscFunctionReturn(PETSC_SUCCESS);
    699: }

    701: /*@
    702:   PetscLogStateClassRegister - Register a class to with a `PetscLogState` used by `PetscLogHandler`s.

    704:   Logically collective on `PETSC_COMM_WORLD`

    706:   Input Parameters:
    707: + state - a `PetscLogState`
    708: . name  - the name of a class registered with `PetscClassIdRegister()`
    709: - id    - the `PetscClassId` obtained from `PetscClassIdRegister()`

    711:   Output Parameter:
    712: . logclass - a `PetscLogClass` for this class with this state

    714:   Level: developer

    716:   Note:
    717:   Classes are automatically registered with PETSc's global logging state (`PetscLogGetState()`), so this
    718:   is only needed for non-global states.

    720: .seealso: [](ch_profiling), `PetscLogStateClassGetInfo()` `PetscLogStateGetClassFromName()`, `PetscLogStateGetClassFromClassId()`
    721: @*/
    722: PetscErrorCode PetscLogStateClassRegister(PetscLogState state, const char name[], PetscClassId id, PetscLogClass *logclass)
    723: {
    724:   PetscFunctionBegin;
    725:   PetscCall(PetscLogRegistryClassRegister(state->registry, name, id, logclass));
    726:   PetscFunctionReturn(PETSC_SUCCESS);
    727: }

    729: /*@
    730:   PetscLogStateClassGetInfo - Get the registration information of an class

    732:   Not collective

    734:   Input Parameters:
    735: + state - a `PetscLogState`
    736: - clss  - a registered `PetscLogClass`

    738:   Output Parameter:
    739: . info - the `PetscLogClassInfo` of the class will be copied into info

    741:   Level: developer

    743: .seealso: [](ch_profiling), `PetscLogState`, `PetscLogStateClassRegister()`, `PetscLogStateGetClassFromName()`
    744: @*/
    745: PetscErrorCode PetscLogStateClassGetInfo(PetscLogState state, PetscLogClass clss, PetscLogClassInfo *info)
    746: {
    747:   PetscFunctionBegin;
    748:   PetscCall(PetscLogRegistryClassGetInfo(state->registry, clss, info));
    749:   PetscFunctionReturn(PETSC_SUCCESS);
    750: }