Timers and sleeps
=================

Sleeping for some time
----------------------

For waiting on the current thread for a certain time, you can use the following
function:

.. function:: int tio_sleep(unsigned long ms)

	Sleep for a certain count of milliseconds.

Measuring time with timers
--------------------------

For measuring time, you can use libtio's timers.

.. type:: tio_timer_t

	A timer (as a private structure).

.. function:: int tio_get_timer(tio_timer_t **timer)

	Create a timer and start counting time. When you're done using the
	timer, you should free the timer using :c:func:`tio_free_timer`.

.. function:: void tio_free_timer(tio_timer_t *timer)

	Free a timer.

.. function:: int tio_get_spent_time(tio_timer_t *timer, unsigned long *spentp)

	Get the spent time since the timer creation, in milliseconds.

An example usage is the following:

.. code-block:: c

	#include <libtio.h>

	int main(void)
	{
		tio_timer_t *timer = NULL;
		int err;
		unsigned long start, end;
		int ret = EXIT_FAILURE;

		if ((err = tio_get_timer(&timer))) {
			fprintf(stderr, "could not create the timer: %s\n",
				tio_error_desc(err));
			goto fail;
		}

		if ((err = tio_get_spent_time(timer, &start))) {
			fprintf(stderr, "could not get the timer start: %s\n",
				tio_error_desc(err));
			goto fail;
		}

		tio_sleep(1234);

		if ((err = tio_get_spent_time(timer, &end))) {
			fprintf(stderr, "could not get the timer end: %s\n",
				tio_error_desc(err));
			goto fail;
		}

		fprintf(stderr, "Spent %lu ms waiting.\n", end - start);
		ret = EXIT_SUCCESS;
	fail:
		tio_free_timer(timer);
		return (ret);
	}