.. SPDX-FileCopyrightText: 2025 Intel Corporation
..
.. SPDX-License-Identifier: CC-BY-4.0

.. _onemath_device_rng_count_engine_adaptor:

Count Engine Adaptor
====================

``count_engine_adaptor`` is a random number engine adaptor that counts how many times
random 32 bits were taken from the engine during the ``generate`` call.

.. rubric:: Description

This adaptor helps to query how many random numbers were taken from
an engine during the ``generate`` call. Especially it's useful for distributions
based on the acceptance-rejection algorithms, e.g. ``beta``, ``gamma``.

class count_engine_adaptor
--------------------------

.. rubric:: Syntax

.. code-block:: cpp

   namespace oneapi::math::rng::device {
    template <typename Engine>
    class count_engine_adaptor {
    public:
        static constexpr std::int32_t vec_size = Engine::vec_size;

        // ctors
        explicit count_engine_adaptor(const Engine& engine);
        explicit count_engine_adaptor(Engine&& engine);

        template <typename... Params>
        count_engine_adaptor(Params... params);

        // getters
        std::int64_t get_count() const;
        const Engine& base() const;
    };
  }

.. container:: section

    .. rubric:: Class Template Parameters

    Engine
        Describes the type of the engine that ``count_engine_adaptor``
        is constructed over.

.. container:: section

    .. rubric:: Class Members

    .. list-table::
        :header-rows: 1

        * - Routine
          - Description
        * - ``explicit count_engine_adaptor(const Engine& engine)``
          - Constructs the adaptor over ``engine``.
        * - ``explicit count_engine_adaptor(Engine&& engine)``
          - Constructs the adaptor over ``engine`` by moving.
        * - ``count_engine_adaptor(Params... params)``
          - Constructs the adaptor generating an engine inside. ``params`` is a
            pack of input parameters to create an engine.
        * - ``std::int64_t get_count() const``
          - This method returns the amount of random numbers generated by ``generate``.
        * - ``const Engine& base() const``
          - Returns the underlying engine.

.. rubric:: Example

.. code-block:: cpp

    namespace rng_device = oneapi::math::rng::device;

    sycl::event my_event = q.parallel_for({n}, [=](std::size_t idx) {
        // Some code...

        rng_device::count_engine_adaptor<rng_device::mcg59<VecSize>> adaptor(seed, idx);
        r[idx] = rng_device::generate(distr, adaptor);

        consumed[idx] = adaptor.get_count();

        // continue work with engine if needed
        auto engine = adaptor.base();
        // ...
    });


**Parent topic:** :ref:`onemath_device_rng_adaptors`