UniqueToken.md: API documentation for UniqueToken.md

[ajpowelsnl]

This PR is the first draft of API documentation for UniqueToken capability and is linked to the #5140 "catch all" Documentation issue.

[JBludau]

there is a lot of whitespace in the c++ code that looks akward given the style we use in the rest of the documentation.

[crtrott]

Document the extra constructor for UniqueTokenScope==Global as:

UniqueToken(size_type max_size, execution_space space = execution_space()) requires(TokenScope == Global);

[ajpowelsnl]

Document the extra constructor for UniqueTokenScope==Global as:

UniqueToken(size_type max_size, execution_space space = execution_space()) requires(TokenScope == Global);

Done

[JBludau]

Looking at the implementation I want to suggest some changes. But someone should verify.

[JBludau]

Suggested change

	``UniqueToken`` is a portable way to acquire a unique ID for calling a thread (``thread-id`` is not portable execution environments). ``UniqueToken`` is thus analogous to ``thread-id``, and has a ``UniqueTokenScope`` template parameter (default: ``Instance``, but can be ``Global``).
	``UniqueToken`` is a portable way to acquire a unique ID identifying a thread. The scope of the unique ID is selected via the ``UniqueTokenScope`` template parameter (defaults to ``Instance``, but can be set to``Global``).

[JBludau]

Suggested change

* ``UniqueTokenScope``: defaults to ``Instance``, but ``Global`` can be employed when thread awareness is needed for more than one ``ExecutionSpace`` instance, as in the case of submitting concurrent kernels to CUDA streams.

moved to the parameters above

[JBludau]

Suggested change

	.. cppkokkos:class:: template <class ExecutionSpace, UniqueTokenScope :: Global> UniqueToken
	.. cppkokkos:class:: template <class ExecutionSpace=DefaultExecutionSpace, UniqueTokenScope = UniqueTokenScope::Instance> UniqueToken

[JBludau]

Suggested change

	Parameters
	-----------
	* ``ExecutionSpace``: See `Execution Spaces <../execution_spaces.html>`_
	.. note::
	In a parallel region, before the main computation, a pool of ``UniqueToken`` (integer) Id is generated, and each Id is released following iteration.
	.. warning::
	``UniqueToken <ExecutionSpace> token`` *can* be called inside a parallel region, *but* must be released at the end of *each* iteration.
	Parameters
	-----------
	* ``ExecutionSpace``: See `Execution Spaces <../execution_spaces.html>`_
	* ``UniqueTokenScope``: defaults to ``Instance`` which results in every instance of ``UniqueToken`` being independent. In contrast ``Global`` uses one set of IDs for all instances.

[JBludau]

Suggested change

	Constructors
	-------------
	.. cppkokkos:function:: UniqueToken(size_t max_size, ExecutionSpace execution_space, UniqueTokenScope :: Global)
	Constructors
	-------------
	.. cppkokkos:function:: UniqueToken(ExecutionSpace execution_space = ExecutionSpace())
	Additionally for ``UniqueTokenScope==Instance``
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	.. cppkokkos:function:: UniqueToken(size_t max_size, ExecutionSpace execution_space=ExecutionSpace())
	Sets an upper bound to the number of tokens. Requires ``max_size <= execution_space.concurrency()``
	Token Interface
	---------------
	.. cppkokkos:function:: size_type size()
	Returns the size of the token pool
	.. cppkokkos:function:: size_type acquire()
	Returns the token for the executing tread
	.. warning::
	Acquired tokens *must* be released at the end of the parallel region in which they were acquired.
	.. cppkokkos:function:: void release(size_type idx)
	Releases the passed token

@crtrott can you verify that it is max_size <= execution_space.concurrency() ... the comment in https://github.com/kokkos/kokkos/blob/d4af7c8302ecb4280c6215497bb2e39f9ed83c3f/core/src/Kokkos_UniqueToken.hpp#L78 would suggest otherwise, but the following lines suggest the opposite in my understanding. But I might be wrong here :-D

[JBludau]

Suggested change

	int id = token . acquire ();
	RandomGen gen = pool (id );
	// Computation Body
	token . release (id );
	auto id = token.acquire ();
	RandomGen gen = pool (id );
	// Computation Body
	token.release (id );

[JBludau]

Suggested change

	void foo () {
	UniqueToken < ExecSpace , UniqueTokenScope :: Global > token_foo ;
	parallel_for ("L", RangePolicy < ExecSpace >( stream1 ,0,N), functor_a ( token_foo ));}
	void foo () {
	UniqueToken < ExecSpace , UniqueTokenScope :: Global > token_foo ;
	parallel_for ("L", RangePolicy < ExecSpace >( stream1 ,0,N), functor_a ( token_foo ));
	}

[JBludau]

Suggested change

	void bar () {
	UniqueToken < ExecSpace , UniqueTokenScope :: Global > token_bar ;
	parallel_for ("L", RangePolicy < ExecSpace >( stream2 ,0,N), functor_b ( token_bar ));}
	void bar () {
	UniqueToken < ExecSpace , UniqueTokenScope :: Global > token_bar ;
	parallel_for ("L", RangePolicy < ExecSpace >( stream2 ,0,N), functor_b ( token_bar ));
	}

[JBludau]

Document the extra constructor for UniqueTokenScope==Global as:

UniqueToken(size_type max_size, execution_space space = execution_space()) requires(TokenScope == Global);

Shouldn't it be TokenScope == Instance for the ctor to take a max_size?