nuttx/include/pthread.h

/************************************************************
 * pthread.h
 *
 *   Copyright (C) 2007 Gregory Nutt. All rights reserved.
 *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 * 3. Neither the name Gregory Nutt nor the names of its contributors may be
 *    used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 ************************************************************/

#ifndef __PTHREAD_H
#define __PTHREAD_H

/************************************************************
 * Included Files
 ************************************************************/

#include <nuttx/config.h>   /* Default settings */
#include <nuttx/compiler.h> /* Compiler settings */
#include <sys/types.h>      /* Needed for general types */
#include <semaphore.h>      /* Needed for sem_t */
#include <time.h>           /* Needed for struct timespec */
#include <nuttx/compiler.h> /* For noreturn_function */

/************************************************************
 * Compilation Switches
 ************************************************************/

/* Standard POSIX switches */

#ifndef _POSIX_THREADS
#define _POSIX_THREADS
#endif
#ifndef _POSIX_THREAD_ATTR_STACKSIZE
#define _POSIX_THREAD_ATTR_STACKSIZE
#endif

/************************************************************
 * Definitions
 ************************************************************/

#define PTHREAD_PROCESS_PRIVATE  0
#define PTHREAD_PROCESS_SHARED   1

#define PTHREAD_STACK_MIN        CONFIG_PTHREAD_STACK_MIN
#define PTHREAD_STACK_DEFAULT    CONFIG_PTHREAD_STACK_DEFAULT

#define PTHREAD_INHERIT_SCHED    0
#define PTHREAD_EXPLICIT_SCHED   1

#define PTHREAD_PRIO_NONE        0
#define PTHREAD_PRIO_INHERIT     1
#define PTHREAD_PRIO_PROTECT     2

#define PTHREAD_DEFAULT_PRIORITY 100

/* Cancellation states returned by pthread_cancelstate() */

#define PTHREAD_CANCEL_ENABLE    (0)
#define PTHREAD_CANCEL_DISABLE   (1)

/* Thread return value when a pthread is canceled */

# define PTHREAD_CANCELED        ((FAR void*)ERROR)

/************************************************************
 * Global Type Declarations
 ************************************************************/

#ifdef __cplusplus
#define EXTERN extern "C"
extern "C" {
#else
#define EXTERN extern
#endif

/*----------------------------------------------------------*
  PTHREAD-SPECIFIC TYPES
 *----------------------------------------------------------*/

typedef int             pthread_key_t;
typedef FAR void       *pthread_addr_t;
typedef pthread_addr_t  any_t;

typedef pthread_addr_t (*pthread_startroutine_t)(pthread_addr_t);
typedef pthread_startroutine_t	pthread_func_t;

struct pthread_addr_s
{
  size_t stacksize;    /* Size of the stack allocated for the pthead */
  short  priority;     /* Priority of the pthread */
  ubyte  policy;       /* Pthread scheduler policy */
  ubyte  inheritsched; /* Inherit parent prio/policy? */
};
typedef struct pthread_addr_s pthread_attr_t;

typedef pid_t pthread_t;

typedef int pthread_condattr_t;

struct pthread_cond_s
{
  sem_t sem;
};
typedef struct pthread_cond_s pthread_cond_t;
#define PTHREAD_COND_INITIALIZER {{0, 0xffff}}

struct pthread_mutexattr_s
{
  int pshared;
};
typedef struct pthread_mutexattr_s pthread_mutexattr_t;

struct pthread_mutex_s
{
  int   pid;
  sem_t sem;
};
typedef struct pthread_mutex_s pthread_mutex_t;
#define PTHREAD_MUTEX_INITIALIZER {0, {1, 0xffff}}

/************************************************************
 * Global Variables
 ************************************************************/

/************************************************************
 * Global Function Prototypes
 ************************************************************/
/*----------------------------------------------------------*
 * Initializes a thread attributes object (attr) with default
 * values for all of the individual attributes used by a
 * given implementation.
 *----------------------------------------------------------*/

EXTERN int pthread_attr_init(pthread_attr_t *attr);

/*----------------------------------------------------------*
 * An attributes object can be deleted when it is no longer
 * needed.
 *----------------------------------------------------------*/

EXTERN int pthread_attr_destroy(pthread_attr_t *attr);

/*----------------------------------------------------------*
 * Set or obtain the default scheduling algorithm
 *----------------------------------------------------------*/

EXTERN int pthread_attr_setschedpolicy(pthread_attr_t *attr,
                                       int policy);
EXTERN int pthread_attr_getschedpolicy(pthread_attr_t *attr,
                                       int *policy);
EXTERN int pthread_attr_setschedparam(pthread_attr_t *attr,
				      const struct sched_param *param);
EXTERN int pthread_attr_getschedparam(pthread_attr_t *attr,
				      struct sched_param *param);
EXTERN int pthread_attr_setinheritsched(pthread_attr_t *attr,
					int inheritsched);
EXTERN int pthread_attr_getinheritsched(const pthread_attr_t *attr,
					int *inheritsched);

/*----------------------------------------------------------*
 * Set or obtain the default stack size
 *----------------------------------------------------------*/

EXTERN int pthread_attr_setstacksize(pthread_attr_t *attr,
                                     long stacksize);
EXTERN int pthread_attr_getstacksize(pthread_attr_t *attr,
                                     long *stackaddr);

/*----------------------------------------------------------*
 * To create a thread object and runnable thread, a routine
 * must be specified as the new thread's start routine.  An
 * argument may be passed to this routine, as an untyped
 * address; an untyped address may also be returned as the
 * routine's value.  An attributes object may be used to
 * specify details about the kind of thread being created.
 *----------------------------------------------------------*/

EXTERN int pthread_create(pthread_t *thread,
                          pthread_attr_t *attr,
			  pthread_startroutine_t startRoutine,
			  pthread_addr_t arg);

/*----------------------------------------------------------*
 * A thread object may be "detached" to specify that the
 * return value and completion status will not be requested.
 *----------------------------------------------------------*/

EXTERN int pthread_detach(pthread_t thread);

/*----------------------------------------------------------*
 * A thread may terminate it's own execution or the
 * execution of another thread.
 *----------------------------------------------------------*/

EXTERN void pthread_exit(pthread_addr_t value) noreturn_function;
EXTERN int  pthread_cancel(pthread_t thread);
EXTERN int  pthread_setcancelstate(int state, int *oldstate);
EXTERN void pthread_testcancel(void);

/*----------------------------------------------------------*
 * A thread can await termination of another thread and retrieve
 * the return value of the thread.
 *----------------------------------------------------------*/

EXTERN int pthread_join(pthread_t thread,
                        pthread_addr_t *value);

/*----------------------------------------------------------*
 * A thread may tell the scheduler that its processor can be
 * made available.
 *----------------------------------------------------------*/

EXTERN void pthread_yield(void);

/*----------------------------------------------------------*
 * A thread may obtain a copy of its own thread handle.
 *----------------------------------------------------------*/

#define pthread_self() ((pthread_t)getpid())

/*----------------------------------------------------------*
 * Compare to thread IDs.
 *----------------------------------------------------------*/

#define pthread_equal(t1,t2) (t1 == t2)

/*----------------------------------------------------------*
 * Thread scheduling parameters
 *----------------------------------------------------------*/

EXTERN int pthread_getschedparam(pthread_t thread,
                                 int *policy,
				 struct sched_param *param);
EXTERN int pthread_setschedparam(pthread_t thread, int policy,
				 const struct sched_param *param);

/*----------------------------------------------------------*
 * Thread-specific Data Interfaces
 *----------------------------------------------------------*/

EXTERN int pthread_key_create(pthread_key_t *key,
			      FAR void (*destructor)(FAR void*));
EXTERN int pthread_setspecific(pthread_key_t key, FAR void *value);
EXTERN FAR void *pthread_getspecific(pthread_key_t key);
EXTERN int pthread_key_delete(pthread_key_t key);

/*----------------------------------------------------------*
 * Create, operate on, and destroy mutex attributes.
 *----------------------------------------------------------*/

EXTERN int pthread_mutexattr_init(pthread_mutexattr_t *attr);
EXTERN int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
EXTERN int pthread_mutexattr_getpshared(pthread_mutexattr_t *attr,
					int *pshared);
EXTERN int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
					int pshared);

/*----------------------------------------------------------*
 * The following routines create, delete, lock and unlock
 * mutexes.
 *----------------------------------------------------------*/

EXTERN int pthread_mutex_init(pthread_mutex_t *mutex,
			      pthread_mutexattr_t *attr);
EXTERN int pthread_mutex_destroy(pthread_mutex_t *mutex);
EXTERN int pthread_mutex_lock(pthread_mutex_t *mutex);
EXTERN int pthread_mutex_trylock(pthread_mutex_t *mutex);
EXTERN int pthread_mutex_unlock(pthread_mutex_t *mutex);

/*----------------------------------------------------------*
 * Operations on condition variables
 *----------------------------------------------------------*/

EXTERN int pthread_condattr_init(pthread_condattr_t *attr);
EXTERN int pthread_condattr_destroy(pthread_condattr_t *attr);

/*----------------------------------------------------------*
 * A thread can create and delete condition variables.
 *----------------------------------------------------------*/

EXTERN int pthread_cond_init(pthread_cond_t *cond,
                             pthread_condattr_t *attr);
EXTERN int pthread_cond_destroy(pthread_cond_t *cond);

/*----------------------------------------------------------*
 * A thread can signal to and broadcast on a condition variable.
 *----------------------------------------------------------*/

EXTERN int pthread_cond_broadcast(pthread_cond_t *cond);
EXTERN int pthread_cond_signal(pthread_cond_t *cond);

/*----------------------------------------------------------*
 * A thread can wait for a condition variable to be signalled
 * or broadcast.
 *----------------------------------------------------------*/

EXTERN int pthread_cond_wait(pthread_cond_t *cond,
                             pthread_mutex_t *mutex);

/*----------------------------------------------------------*
 * A thread can perform a timed wait on a condition variable.
 *----------------------------------------------------------*/

EXTERN int pthread_cond_timedwait(pthread_cond_t *cond,
                                  pthread_mutex_t *mutex,
                                  const struct timespec *abstime);

#undef EXTERN
#ifdef __cplusplus
}
#endif

#endif /* __PTHREAD_H */