once.h

Go to the documentation of this file.

/* KallistiOS ##version##

   include/kos/once.h
   Copyright (C) 2009, 2010 Lawrence Sebald

*/

#ifndef __KOS_ONCE_H
#define __KOS_ONCE_H

/** \file   kos/once.h
    \brief  Dynamic package initialization.

    This file provides definitions for an object that functions the same way as
    the pthread_once_t function does from the POSIX specification. This object
    type and functionality is generally used to make sure that a given
    initialization function is run once, and only once, no matter how many
    threads attempt to call it.

    \author Lawrence Sebald
*/

#include <sys/cdefs.h>

__BEGIN_DECLS

/** \brief  Object type backing kthread_once.

    This object type should always be initialized with the KTHREAD_ONCE_INIT
    macro.

    \headerfile kos/once.h
*/
typedef struct {
    int initialized;
    int run;
} kthread_once_t;

/** \brief  Initializer for a kthread_once_t object. */
#define KTHREAD_ONCE_INIT { 1, 0 }

/** \brief  Run a function once.

    This function, when used with a kthread_once_t object (that should be shared
    amongst all threads) will run the init_routine once, and set the
    once_control to make sure that the function will not be run again (as long
    as all threads attempt to call the init_routine through this function.

    \param  once_control    The kthread_once_t object to run against.
    \param  init_routine    The function to call.
    \retval -1      On failure, and sets errno to one of the following: ENOMEM
                    if out of memory, EPERM if called inside an interrupt, or
                    EINTR if interrupted.
    \retval 0       On success. */
int kthread_once(kthread_once_t *once_control, void (*init_routine)(void));

__END_DECLS

#endif /* !__KOS_ONCE_H */