tools/gcc4libstdxx/ecos/compat/posix/current/include/pthread.h

   1 #ifndef CYGONCE_PTHREAD_H
   2 #define CYGONCE_PTHREAD_H
   3 //=============================================================================
   4 //
   5 //      pthread.h
   6 //
   7 //      POSIX pthread header
   8 //
   9 //=============================================================================
  10 // ####ECOSGPLCOPYRIGHTBEGIN####
  11 // -------------------------------------------
  12 // This file is part of eCos, the Embedded Configurable Operating System.
  13 // Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
  14 //
  15 // eCos is free software; you can redistribute it and/or modify it under
  16 // the terms of the GNU General Public License as published by the Free
  17 // Software Foundation; either version 2 or (at your option) any later
  18 // version.
  19 //
  20 // eCos is distributed in the hope that it will be useful, but WITHOUT
  21 // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  22 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  23 // for more details.
  24 //
  25 // You should have received a copy of the GNU General Public License
  26 // along with eCos; if not, write to the Free Software Foundation, Inc.,
  27 // 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  28 //
  29 // As a special exception, if other files instantiate templates or use
  30 // macros or inline functions from this file, or you compile this file
  31 // and link it with other works to produce a work based on this file,
  32 // this file does not by itself cause the resulting work to be covered by
  33 // the GNU General Public License. However the source code for this file
  34 // must still be made available in accordance with section (3) of the GNU
  35 // General Public License v2.
  36 //
  37 // This exception does not invalidate any other reasons why a work based
  38 // on this file might be covered by the GNU General Public License.
  39 // -------------------------------------------
  40 // ####ECOSGPLCOPYRIGHTEND####
  41 //=============================================================================
  42 //#####DESCRIPTIONBEGIN####
  43 //
  44 // Author(s):     nickg
  45 // Contributors:  nickg
  46 // Date:          2000-03-17
  47 // Purpose:       POSIX pthread header
  48 // Description:   This header contains all the definitions needed to support
  49 //                pthreads under eCos. The reader is referred to the POSIX
  50 //                standard or equivalent documentation for details of the
  51 //                functionality contained herein.
  52 //
  53 // Usage:
  54 //              #include <pthread.h>
  55 //              ...
  56 //
  57 //
  58 //####DESCRIPTIONEND####
  59 //
  60 //=============================================================================
  61
  62 #include <pkgconf/hal.h>
  63 #include <pkgconf/kernel.h>
  64 #include <pkgconf/posix.h>
  65
  66 #include <cyg/infra/cyg_type.h>
  67
  68 #include <cyg/hal/hal_arch.h>   // CYGNUM_HAL_STACK_SIZE_MINIMUM
  69
  70 #include <stddef.h>             // NULL, size_t
  71
  72 #include <limits.h>
  73
  74 #include <sys/types.h>
  75
  76 #include <sched.h>              // SCHED_*
  77 #include <time.h>
  78 //=============================================================================
  79 // General thread operations
  80
  81 //-----------------------------------------------------------------------------
  82 // Thread creation and management.
  83
  84 // Create a thread.
  85 __externC int pthread_create (pthread_t *__pthread,
  86                               const pthread_attr_t *__attr,
  87                               void *(*__start_routine) (void *),
  88                               void *__arg);
  89
  90 // Get current thread id.
  91 __externC pthread_t pthread_self (void);
  92
  93 // Compare two thread identifiers.
  94 __externC int pthread_equal (pthread_t __thread1, pthread_t __thread2);
  95
  96 // Terminate current thread.
  97 __externC void pthread_exit (void *__retval) CYGBLD_ATTRIB_NORET;
  98
  99 // Wait for the thread to terminate. If thread_return is not NULL then
 100 // the retval from the thread's call to pthread_exit() is stored at
 101 // *thread_return.
 102 __externC int pthread_join (pthread_t __pthread, void **__thread_return);
 103
 104 // Set the detachstate of the thread to "detached". The thread then does not
 105 // need to be joined and its resources will be freed when it exits.
 106 __externC int pthread_detach (pthread_t __pthread);
 107
 108 //-----------------------------------------------------------------------------
 109 // Thread attribute handling.
 110
 111 // Initialize attributes object with default attributes:
 112 // detachstate          == PTHREAD_JOINABLE
 113 // scope                == PTHREAD_SCOPE_SYSTEM
 114 // inheritsched         == PTHREAD_EXPLICIT_SCHED
 115 // schedpolicy          == SCHED_OTHER
 116 // schedparam           == unset
 117 // stackaddr            == unset
 118 // stacksize            == 0
 119 //
 120 __externC int pthread_attr_init (pthread_attr_t *__attr);
 121
 122 // Destroy thread attributes object
 123 __externC int pthread_attr_destroy (pthread_attr_t *__attr);
 124
 125
 126 // Set the detachstate attribute
 127 __externC int pthread_attr_setdetachstate (pthread_attr_t *__attr,
 128                                            int __detachstate);
 129
 130 // Get the detachstate attribute
 131 __externC int pthread_attr_getdetachstate (const pthread_attr_t *__attr,
 132                                            int *__detachstate);
 133
 134
 135 // Set scheduling contention scope
 136 __externC int pthread_attr_setscope (pthread_attr_t *__attr, int __scope);
 137
 138 // Get scheduling contention scope
 139 __externC int pthread_attr_getscope (const pthread_attr_t *__attr, int *__scope);
 140
 141
 142 // Set scheduling inheritance attribute
 143 __externC int pthread_attr_setinheritsched (pthread_attr_t *__attr, int __inherit);
 144
 145 // Get scheduling inheritance attribute
 146 __externC int pthread_attr_getinheritsched (const pthread_attr_t *__attr,
 147                                             int *__inherit);
 148
 149
 150 // Set scheduling policy
 151 __externC int pthread_attr_setschedpolicy (pthread_attr_t *__attr, int __policy);
 152
 153 // Get scheduling policy
 154 __externC int pthread_attr_getschedpolicy (const pthread_attr_t *__attr,
 155                                            int *__policy);
 156
 157
 158 // Set scheduling parameters
 159 __externC int pthread_attr_setschedparam (pthread_attr_t *__attr,
 160                                           const struct sched_param *__param);
 161
 162 // Get scheduling parameters
 163 __externC int pthread_attr_getschedparam (const pthread_attr_t *__attr,
 164                                           struct sched_param *__param);
 165
 166
 167 // Set starting address of stack. Whether this is at the start or end of
 168 // the memory block allocated for the stack depends on whether the stack
 169 // grows up or down.
 170 __externC int pthread_attr_setstackaddr (pthread_attr_t *__attr, void *__stackaddr);
 171
 172 // Get any previously set stack address.
 173 __externC int pthread_attr_getstackaddr (const pthread_attr_t *__attr,
 174                                          void **__stackaddr);
 175
 176
 177 // Set minimum creation stack size.
 178 __externC int pthread_attr_setstacksize (pthread_attr_t *__attr,
 179                                          size_t __stacksize);
 180
 181 // Get current minimal stack size.
 182 __externC int pthread_attr_getstacksize (const pthread_attr_t *__attr,
 183                                          size_t *__stacksize);
 184
 185 //-----------------------------------------------------------------------------
 186 // Thread scheduling controls
 187
 188 // Set scheduling policy and parameters for the thread
 189 __externC int pthread_setschedparam (pthread_t __pthread,
 190                                      int __policy,
 191                                      const struct sched_param *__param);
 192
 193 // Get scheduling policy and parameters for the thread
 194 __externC int pthread_getschedparam (pthread_t __pthread,
 195                                      int *__policy,
 196                                      struct sched_param *__param);
 197
 198
 199
 200 //=============================================================================
 201 // Dynamic package initialization
 202
 203 // Initializer for pthread_once_t instances
 204 #define PTHREAD_ONCE_INIT       0
 205
 206 // Call init_routine just the once per control variable.
 207 __externC int pthread_once (pthread_once_t *__once_control,
 208                             void (*__init_routine) (void));
 209
 210
 211
 212 //=============================================================================
 213 //Thread specific data
 214
 215 // Create a key to identify a location in the thread specific data area.
 216 // Each thread has its own distinct thread-specific data area but all are
 217 // addressed by the same keys. The destructor function is called whenever a
 218 // thread exits and the value associated with the key is non-NULL.
 219 __externC int pthread_key_create (pthread_key_t *__key,
 220                                   void (*__destructor) (void *));
 221
 222 // Delete key.
 223 __externC int pthread_key_delete (pthread_key_t __key);
 224
 225 // Store the pointer value in the thread-specific data slot addressed
 226 // by the key.
 227 __externC int pthread_setspecific (pthread_key_t __key, const void *__pointer);
 228
 229 // Retrieve the pointer value in the thread-specific data slot addressed
 230 // by the key.
 231 __externC void *pthread_getspecific (pthread_key_t __key);
 232
 233
 234
 235 //=============================================================================
 236 // Thread Cancellation
 237
 238 //-----------------------------------------------------------------------------
 239 // Data structure used to manage cleanup functions
 240
 241 struct pthread_cleanup_buffer
 242 {
 243     struct pthread_cleanup_buffer *prev;        // Chain cleanup buffers
 244     void (*routine) (void *);                   // Function to call
 245     void *arg;                                  // Arg to pass
 246 };
 247
 248 //-----------------------------------------------------------------------------
 249 // Thread cancelled return value.
 250 // This is a value returned as the retval in pthread_join() of a
 251 // thread that has been cancelled. By making it the address of a
 252 // location we define we can ensure that it differs from NULL and any
 253 // other valid pointer (as required by the standard).
 254
 255 __externC int pthread_canceled_dummy_var;
 256
 257 #define PTHREAD_CANCELED                ((void *)(&pthread_canceled_dummy_var))
 258
 259 //-----------------------------------------------------------------------------
 260 // Cancelability enable and type
 261
 262 #define PTHREAD_CANCEL_ENABLE           1
 263 #define PTHREAD_CANCEL_DISABLE          2
 264
 265 #define PTHREAD_CANCEL_ASYNCHRONOUS     1
 266 #define PTHREAD_CANCEL_DEFERRED         2
 267
 268 //-----------------------------------------------------------------------------
 269 // Functions
 270
 271 // Set cancel state of current thread to ENABLE or DISABLE.
 272 // Returns old state in *oldstate.
 273 __externC int pthread_setcancelstate (int __state, int *__oldstate);
 274
 275 // Set cancel type of current thread to ASYNCHRONOUS or DEFERRED.
 276 // Returns old type in *oldtype.
 277 __externC int pthread_setcanceltype (int __type, int *__oldtype);
 278
 279 // Cancel the thread.
 280 __externC int pthread_cancel (pthread_t __pthread);
 281
 282 // Test for a pending cancellation for the current thread and terminate
 283 // the thread if there is one.
 284 __externC void pthread_testcancel (void);
 285
 286 // Install a cleanup routine.
 287 // Note that pthread_cleanup_push() and pthread_cleanup_pop() are macros that
 288 // must be used in matching pairs and at the same brace nesting level.
 289 #define pthread_cleanup_push(__routine, __arg)                          \
 290     {                                                                   \
 291         struct pthread_cleanup_buffer _buffer_;                         \
 292         pthread_cleanup_push_inner (&_buffer_, (__routine), (__arg));
 293
 294 // Remove a cleanup handler installed by the matching pthread_cleanup_push().
 295 // If execute is non-zero, the handler function is called.
 296 #define pthread_cleanup_pop(__execute)                          \
 297         pthread_cleanup_pop_inner (&_buffer_, (__execute));     \
 298     }
 299
 300
 301 // These two functions actually implement the cleanup push and pop functionality.
 302 __externC void pthread_cleanup_push_inner (struct pthread_cleanup_buffer *__buffer,
 303                                            void (*__routine) (void *),
 304                                            void *__arg);
 305
 306 __externC void pthread_cleanup_pop_inner (struct pthread_cleanup_buffer *__buffer,
 307                                           int __execute);
 308
 309
 310
 311 __externC int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);
 312
 313
 314
 315
 316
 317 // -------------------------------------------------------------------------
 318 // eCos-specific function to measure stack usage of the supplied thread
 319
 320 #ifdef CYGFUN_KERNEL_THREADS_STACK_MEASUREMENT
 321 __externC size_t pthread_measure_stack_usage (pthread_t __pthread);
 322 #endif
 323
 324
 325 //-----------------------------------------------------------------------------
 326 #endif // ifndef CYGONCE_PTHREAD_H
 327 // End of pthread.h