SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2021 embedded brains GmbH & Co. KG
enabled-by: true
functional-type: action
links:
- role: interface-function
  uid: ../if/futex-wake
- role: function-implementation
  uid: /score/tq/req/flush-fifo
- role: requirement-refinement
  uid: futex
post-conditions:
- name: Result
  states:
  - name: Count
    test-code: |
      /* This result is checked by Flush() */
    text: |
      The return status of ${../if/futex-wake:/name} shall be the count of threads
      extracted from the thread queue of the futex object.
  test-epilogue: null
  test-prologue: null
- name: Flush
  states:
  - name: 'No'
    test-code: |
      /* This state is checked by Enqueue() */
    text: |
      No thread shall be extracted from the thread queue of the futex object.
  - name: 'Yes'
    test-code: |
      ${/score/tq/req/flush-fifo:/test-run}( &ctx->tq_ctx, true );
    text: |
      The first count threads specified by the ``count`` parameter shall be
      extracted from the thread queue of the futex object in
      ${/glossary/fifo:/term} order.
  test-epilogue: null
  test-prologue: null
pre-conditions:
- name: Count
  states:
  - name: NegativeOrZero
    test-code: |
      /* This state is prepared by Enqueue() */
    text: |
      While the ``count`` parameter is less or equal to than zero.
  - name: Positive
    test-code: |
      /* This state is prepared by Flush() */
    text: |
      While the ``count`` parameter is greater than zero.
  test-epilogue: null
  test-prologue: null
rationale: null
references: []
requirement-type: functional
skip-reasons: {}
test-action: |
  /* The action is performed in the ``Flush`` post-condition ``All`` state. */
test-brief: null
test-cleanup:
  _Futex_Destroy( &ctx->futex );
test-context:
- brief: |
    This member contains the thread queue test context.
  description: null
  member: |
    TQContext tq_ctx;
- brief: |
    This member provides the futex object.
  description: null
  member: |
    struct _Futex_Control futex
- brief: |
    This member provides the futex state.
  description: null
  member: |
    int state
test-context-support: null
test-description: null
test-header: null
test-includes:
- sys/lock.h
- limits.h
- rtems.h
test-local-includes:
- tx-thread-queue.h
- tr-tq-flush-fifo.h
test-prepare: |
  _Futex_Initialize( &ctx->futex );
test-setup:
  brief: null
  code: |
    memset( ctx, 0, sizeof( *ctx ) );
    ctx->tq_ctx.discipline = TQ_FIFO;
    ctx->tq_ctx.wait = TQ_WAIT_FOREVER;
    ctx->tq_ctx.enqueue_prepare = TQDoNothing;
    ctx->tq_ctx.enqueue = Enqueue;
    ctx->tq_ctx.enqueue_done = TQDoNothing;
    ctx->tq_ctx.flush = Flush;
    ctx->tq_ctx.surrender = TQDoNothingSuccessfully;
    ctx->tq_ctx.convert_status = TQConvertStatusPOSIX;
    TQInitialize( &ctx->tq_ctx );
  description: null
test-stop: null
test-support: |
  typedef ${.:/test-context-type} Context;

  static Context *ToContext( TQContext *tq_ctx )
  {
    return RTEMS_CONTAINER_OF( tq_ctx, Context, tq_ctx );
  }

  static Status_Control Enqueue( TQContext *tq_ctx, TQWait wait )
  {
    Context *ctx;
    int      count;
    int      eno;

    ctx = ToContext( tq_ctx );

    count = _Futex_Wake( &ctx->futex, -1 );
    T_eq_int( count, 0 );

    count = _Futex_Wake( &ctx->futex, 0 );
    T_eq_int( count, 0 );

    eno = _Futex_Wait( &ctx->futex, &ctx->state, 0 );
    T_eq_int( eno, 0 );

    return STATUS_BUILD( 0, eno );
  }

  static uint32_t Flush( TQContext *tq_ctx, uint32_t thread_count, bool all )
  {
    Context *ctx;
    int      count;

    (void) thread_count;

    ctx = ToContext( tq_ctx );

    if ( all ) {
      count = _Futex_Wake( &ctx->futex, INT_MAX );
    } else {
      count = _Futex_Wake( &ctx->futex, 1 );
    }

    return (uint32_t) count;
  }
test-target: testsuites/validation/tc-futex-wake.c
test-teardown:
  brief: null
  code: |
    TQDestroy( &ctx->tq_ctx );
  description: null
text: ${.:text-template}
transition-map:
- enabled-by: true
  post-conditions:
    Result: Count
    Flush: 'No'
  pre-conditions:
    Count:
    - NegativeOrZero
- enabled-by: true
  post-conditions:
    Result: Count
    Flush: 'Yes'
  pre-conditions:
    Count:
    - Positive
type: requirement