Threads.h

Go to the documentation of this file.

 
#ifndef __THREADS__
#define __THREADS__
 
#ifndef __MACTYPES__
#include <MacTypes.h>
#endif
 
#ifndef __MIXEDMODE__
#include <MixedMode.h>
#endif
 
#ifndef __MACERRORS__
#include <MacErrors.h>
#endif
 
#if PRAGMA_ONCE
#pragma once
#endif
 
#ifdef __cplusplus
extern "C"
{
#endif
 
#if PRAGMA_IMPORT
#pragma import on
#endif
 
#if PRAGMA_STRUCT_ALIGN
#pragma options align = mac68k
#elif PRAGMA_STRUCT_PACKPUSH
#pragma pack(push, 2)
#elif PRAGMA_STRUCT_PACK
#pragma pack(2)
#endif
 
  /* Thread states*/
  typedef UInt16 ThreadState;
  enum
  {
    kReadyThreadState = 0,
    kStoppedThreadState = 1,
    kRunningThreadState = 2
  };
 
  /* Error codes have been moved to Errors.(pah)*/
 
  /* Thread environment characteristics*/
  typedef void *ThreadTaskRef;
  /* Thread characteristics*/
  typedef UInt32 ThreadStyle;
  enum
  {
    kCooperativeThread = 1L << 0,
    kPreemptiveThread = 1L << 1
  };
 
  /* Thread identifiers*/
  typedef UInt32 ThreadID;
  enum
  {
    kNoThreadID = 0,
    kCurrentThreadID = 1,
    kApplicationThreadID = 2
  };
 
  /* Options when creating a thread*/
  typedef UInt32 ThreadOptions;
  enum
  {
    kNewSuspend = (1 << 0),
    kUsePremadeThread = (1 << 1),
    kCreateIfNeeded = (1 << 2),
    kFPUNotNeeded = (1 << 3),
    kExactMatchThread = (1 << 4)
  };
 
  /* Information supplied to the custom scheduler*/
  struct SchedulerInfoRec
  {
    UInt32 InfoRecSize;
    ThreadID CurrentThreadID;
    ThreadID SuggestedThreadID;
    ThreadID InterruptedCoopThreadID;
  };
  typedef struct SchedulerInfoRec SchedulerInfoRec;
  typedef SchedulerInfoRec *SchedulerInfoRecPtr;
 
  typedef void *voidPtr;
  /* Prototype for thread's entry (main) routine*/
  typedef CALLBACK_API(voidPtr, ThreadEntryProcPtr)(void *threadParam);
  /* Prototype for custom thread scheduler routine*/
  typedef CALLBACK_API(ThreadID,
                       ThreadSchedulerProcPtr)(SchedulerInfoRecPtr schedulerInfo);
  /* Prototype for custom thread switcher routine*/
  typedef CALLBACK_API(void, ThreadSwitchProcPtr)(ThreadID threadBeingSwitched,
                                                  void *switchProcParam);
  /* Prototype for thread termination notification routine*/
  typedef CALLBACK_API(void,
                       ThreadTerminationProcPtr)(ThreadID threadTerminated,
                                                 void *terminationProcParam);
  /* Prototype for debugger NewThread notification*/
  typedef CALLBACK_API(void, DebuggerNewThreadProcPtr)(ThreadID threadCreated);
  /* Prototype for debugger DisposeThread notification*/
  typedef CALLBACK_API(void,
                       DebuggerDisposeThreadProcPtr)(ThreadID threadDeleted);
  /* Prototype for debugger schedule notification*/
  typedef CALLBACK_API(ThreadID, DebuggerThreadSchedulerProcPtr)(
      SchedulerInfoRecPtr schedulerInfo);
  typedef TVECTOR_UPP_TYPE(ThreadEntryProcPtr) ThreadEntryUPP;
  typedef TVECTOR_UPP_TYPE(ThreadSchedulerProcPtr) ThreadSchedulerUPP;
  typedef TVECTOR_UPP_TYPE(ThreadSwitchProcPtr) ThreadSwitchUPP;
  typedef TVECTOR_UPP_TYPE(ThreadTerminationProcPtr) ThreadTerminationUPP;
  typedef TVECTOR_UPP_TYPE(DebuggerNewThreadProcPtr) DebuggerNewThreadUPP;
  typedef TVECTOR_UPP_TYPE(DebuggerDisposeThreadProcPtr) DebuggerDisposeThreadUPP;
  typedef TVECTOR_UPP_TYPE(DebuggerThreadSchedulerProcPtr)
      DebuggerThreadSchedulerUPP;
  ThreadEntryUPP
  NewThreadEntryUPP(ThreadEntryProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
  enum
  {
    uppThreadEntryProcInfo = 0x000000F0
  }; /* pascal 4_bytes Func(4_bytes) */
#ifdef __cplusplus
  inline ThreadEntryUPP NewThreadEntryUPP(ThreadEntryProcPtr userRoutine)
  {
    return userRoutine;
  }
#else
#define NewThreadEntryUPP(userRoutine) (userRoutine)
#endif
#endif
 
  ThreadSchedulerUPP
  NewThreadSchedulerUPP(ThreadSchedulerProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
  enum
  {
    uppThreadSchedulerProcInfo = 0x000000F0
  }; /* pascal 4_bytes Func(4_bytes) */
#ifdef __cplusplus
  inline ThreadSchedulerUPP
  NewThreadSchedulerUPP(ThreadSchedulerProcPtr userRoutine)
  {
    return userRoutine;
  }
#else
#define NewThreadSchedulerUPP(userRoutine) (userRoutine)
#endif
#endif
 
  ThreadSwitchUPP
  NewThreadSwitchUPP(ThreadSwitchProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
  enum
  {
    uppThreadSwitchProcInfo = 0x000003C0
  }; /* pascal no_return_value Func(4_bytes, 4_bytes) */
#ifdef __cplusplus
  inline ThreadSwitchUPP NewThreadSwitchUPP(ThreadSwitchProcPtr userRoutine)
  {
    return userRoutine;
  }
#else
#define NewThreadSwitchUPP(userRoutine) (userRoutine)
#endif
#endif
 
  ThreadTerminationUPP
  NewThreadTerminationUPP(ThreadTerminationProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
  enum
  {
    uppThreadTerminationProcInfo = 0x000003C0
  }; /* pascal no_return_value Func(4_bytes, 4_bytes) */
#ifdef __cplusplus
  inline ThreadTerminationUPP
  NewThreadTerminationUPP(ThreadTerminationProcPtr userRoutine)
  {
    return userRoutine;
  }
#else
#define NewThreadTerminationUPP(userRoutine) (userRoutine)
#endif
#endif
 
  DebuggerNewThreadUPP
  NewDebuggerNewThreadUPP(DebuggerNewThreadProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
  enum
  {
    uppDebuggerNewThreadProcInfo = 0x000000C0
  }; /* pascal no_return_value Func(4_bytes) */
#ifdef __cplusplus
  inline DebuggerNewThreadUPP
  NewDebuggerNewThreadUPP(DebuggerNewThreadProcPtr userRoutine)
  {
    return userRoutine;
  }
#else
#define NewDebuggerNewThreadUPP(userRoutine) (userRoutine)
#endif
#endif
 
  DebuggerDisposeThreadUPP
  NewDebuggerDisposeThreadUPP(DebuggerDisposeThreadProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
  enum
  {
    uppDebuggerDisposeThreadProcInfo = 0x000000C0
  }; /* pascal no_return_value Func(4_bytes) */
#ifdef __cplusplus
  inline DebuggerDisposeThreadUPP
  NewDebuggerDisposeThreadUPP(DebuggerDisposeThreadProcPtr userRoutine)
  {
    return userRoutine;
  }
#else
#define NewDebuggerDisposeThreadUPP(userRoutine) (userRoutine)
#endif
#endif
 
  DebuggerThreadSchedulerUPP
  NewDebuggerThreadSchedulerUPP(DebuggerThreadSchedulerProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
  enum
  {
    uppDebuggerThreadSchedulerProcInfo = 0x000000F0
  }; /* pascal 4_bytes Func(4_bytes) */
#ifdef __cplusplus
  inline DebuggerThreadSchedulerUPP
  NewDebuggerThreadSchedulerUPP(DebuggerThreadSchedulerProcPtr userRoutine)
  {
    return userRoutine;
  }
#else
#define NewDebuggerThreadSchedulerUPP(userRoutine) (userRoutine)
#endif
#endif
 
  void
  DisposeThreadEntryUPP(ThreadEntryUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline void DisposeThreadEntryUPP(ThreadEntryUPP) {}
#else
#define DisposeThreadEntryUPP(userUPP)
#endif
#endif
 
  void
  DisposeThreadSchedulerUPP(ThreadSchedulerUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline void DisposeThreadSchedulerUPP(ThreadSchedulerUPP) {}
#else
#define DisposeThreadSchedulerUPP(userUPP)
#endif
#endif
 
  void
  DisposeThreadSwitchUPP(ThreadSwitchUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline void DisposeThreadSwitchUPP(ThreadSwitchUPP) {}
#else
#define DisposeThreadSwitchUPP(userUPP)
#endif
#endif
 
  void
  DisposeThreadTerminationUPP(ThreadTerminationUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline void DisposeThreadTerminationUPP(ThreadTerminationUPP) {}
#else
#define DisposeThreadTerminationUPP(userUPP)
#endif
#endif
 
  void
  DisposeDebuggerNewThreadUPP(DebuggerNewThreadUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline void DisposeDebuggerNewThreadUPP(DebuggerNewThreadUPP) {}
#else
#define DisposeDebuggerNewThreadUPP(userUPP)
#endif
#endif
 
  void
  DisposeDebuggerDisposeThreadUPP(DebuggerDisposeThreadUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline void DisposeDebuggerDisposeThreadUPP(DebuggerDisposeThreadUPP) {}
#else
#define DisposeDebuggerDisposeThreadUPP(userUPP)
#endif
#endif
 
  void
  DisposeDebuggerThreadSchedulerUPP(DebuggerThreadSchedulerUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline void DisposeDebuggerThreadSchedulerUPP(DebuggerThreadSchedulerUPP) {}
#else
#define DisposeDebuggerThreadSchedulerUPP(userUPP)
#endif
#endif
 
  voidPtr
  InvokeThreadEntryUPP(void *threadParam, ThreadEntryUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline voidPtr InvokeThreadEntryUPP(void *threadParam, ThreadEntryUPP userUPP)
  {
    return (*userUPP)(threadParam);
  }
#else
#define InvokeThreadEntryUPP(threadParam, userUPP) (*userUPP)(threadParam)
#endif
#endif
 
  ThreadID
  InvokeThreadSchedulerUPP(SchedulerInfoRecPtr schedulerInfo,
                           ThreadSchedulerUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline ThreadID InvokeThreadSchedulerUPP(SchedulerInfoRecPtr schedulerInfo,
                                           ThreadSchedulerUPP userUPP)
  {
    return (*userUPP)(schedulerInfo);
  }
#else
#define InvokeThreadSchedulerUPP(schedulerInfo, userUPP) \
  (*userUPP)(schedulerInfo)
#endif
#endif
 
  void
  InvokeThreadSwitchUPP(ThreadID threadBeingSwitched, void *switchProcParam,
                        ThreadSwitchUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline void InvokeThreadSwitchUPP(ThreadID threadBeingSwitched,
                                    void *switchProcParam,
                                    ThreadSwitchUPP userUPP)
  {
    (*userUPP)(threadBeingSwitched, switchProcParam);
  }
#else
#define InvokeThreadSwitchUPP(threadBeingSwitched, switchProcParam, userUPP) \
  (*userUPP)(threadBeingSwitched, switchProcParam)
#endif
#endif
 
  void
  InvokeThreadTerminationUPP(ThreadID threadTerminated,
                             void *terminationProcParam,
                             ThreadTerminationUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline void InvokeThreadTerminationUPP(ThreadID threadTerminated,
                                         void *terminationProcParam,
                                         ThreadTerminationUPP userUPP)
  {
    (*userUPP)(threadTerminated, terminationProcParam);
  }
#else
#define InvokeThreadTerminationUPP(threadTerminated, terminationProcParam, \
                                   userUPP)                                \
  (*userUPP)(threadTerminated, terminationProcParam)
#endif
#endif
 
  void
  InvokeDebuggerNewThreadUPP(ThreadID threadCreated,
                             DebuggerNewThreadUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline void InvokeDebuggerNewThreadUPP(ThreadID threadCreated,
                                         DebuggerNewThreadUPP userUPP)
  {
    (*userUPP)(threadCreated);
  }
#else
#define InvokeDebuggerNewThreadUPP(threadCreated, userUPP) \
  (*userUPP)(threadCreated)
#endif
#endif
 
  void
  InvokeDebuggerDisposeThreadUPP(ThreadID threadDeleted,
                                 DebuggerDisposeThreadUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline void InvokeDebuggerDisposeThreadUPP(ThreadID threadDeleted,
                                             DebuggerDisposeThreadUPP userUPP)
  {
    (*userUPP)(threadDeleted);
  }
#else
#define InvokeDebuggerDisposeThreadUPP(threadDeleted, userUPP) \
  (*userUPP)(threadDeleted)
#endif
#endif
 
  ThreadID
  InvokeDebuggerThreadSchedulerUPP(SchedulerInfoRecPtr schedulerInfo,
                                   DebuggerThreadSchedulerUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
  inline ThreadID
  InvokeDebuggerThreadSchedulerUPP(SchedulerInfoRecPtr schedulerInfo,
                                   DebuggerThreadSchedulerUPP userUPP)
  {
    return (*userUPP)(schedulerInfo);
  }
#else
#define InvokeDebuggerThreadSchedulerUPP(schedulerInfo, userUPP) \
  (*userUPP)(schedulerInfo)
#endif
#endif
 
#if TARGET_OS_MAC && TARGET_CPU_PPC && !OPAQUE_UPP_TYPES
  /* use raw function pointers*/
  typedef ThreadEntryProcPtr ThreadEntryTPP;
  typedef ThreadSchedulerProcPtr ThreadSchedulerTPP;
  typedef ThreadSwitchProcPtr ThreadSwitchTPP;
  typedef ThreadTerminationProcPtr ThreadTerminationTPP;
  typedef DebuggerNewThreadProcPtr DebuggerNewThreadTPP;
  typedef DebuggerDisposeThreadProcPtr DebuggerDisposeThreadTPP;
  typedef DebuggerThreadSchedulerProcPtr DebuggerThreadSchedulerTPP;
#else
/* use UPP's*/
typedef ThreadEntryUPP ThreadEntryTPP;
typedef ThreadSchedulerUPP ThreadSchedulerTPP;
typedef ThreadSwitchUPP ThreadSwitchTPP;
typedef ThreadTerminationUPP ThreadTerminationTPP;
typedef DebuggerNewThreadUPP DebuggerNewThreadTPP;
typedef DebuggerDisposeThreadUPP DebuggerDisposeThreadTPP;
typedef DebuggerThreadSchedulerUPP DebuggerThreadSchedulerTPP;
#endif /* TARGET_OS_MAC && TARGET_CPU_PPC && !OPAQUE_UPP_TYPES */
 
  OSErr
  NewThread(ThreadStyle threadStyle, ThreadEntryTPP threadEntry,
            void *threadParam, Size stackSize, ThreadOptions options,
            void **threadResult, /* can be NULL */
            ThreadID *threadMade);
 
  OSErr
  SetThreadScheduler(ThreadSchedulerTPP threadScheduler);
 
  OSErr
  SetThreadSwitcher(ThreadID thread, ThreadSwitchTPP threadSwitcher,
                    void *switchProcParam, Boolean inOrOut);
 
  OSErr
  SetThreadTerminator(ThreadID thread, ThreadTerminationTPP threadTerminator,
                      void *terminationProcParam);
 
  OSErr
  SetDebuggerNotificationProcs(DebuggerNewThreadTPP notifyNewThread,
                               DebuggerDisposeThreadTPP notifyDisposeThread,
                               DebuggerThreadSchedulerTPP notifyThreadScheduler);
 
  OSErr
  CreateThreadPool(ThreadStyle threadStyle, SInt16 numToCreate, Size stackSize);
 
  OSErr
  GetFreeThreadCount(ThreadStyle threadStyle, SInt16 *freeCount);
 
  OSErr
  GetSpecificFreeThreadCount(ThreadStyle threadStyle, Size stackSize,
                             SInt16 *freeCount);
 
  OSErr
  GetDefaultThreadStackSize(ThreadStyle threadStyle, Size *stackSize);
 
  OSErr
  ThreadCurrentStackSpace(ThreadID thread, UInt32 *freeStack);
 
  OSErr
  DisposeThread(ThreadID threadToDump, void *threadResult, Boolean recycleThread);
 
  OSErr
  YieldToThread(ThreadID suggestedThread);
 
  OSErr
  YieldToAnyThread(void);
 
#if TARGET_OS_MAC
#define MacGetCurrentThread GetCurrentThread
#endif
  OSErr
  MacGetCurrentThread(ThreadID *currentThreadID);
 
  OSErr
  GetThreadState(ThreadID threadToGet, ThreadState *threadState);
 
  OSErr
  SetThreadState(ThreadID threadToSet, ThreadState newState,
                 ThreadID suggestedThread);
 
  OSErr
  SetThreadStateEndCritical(ThreadID threadToSet, ThreadState newState,
                            ThreadID suggestedThread);
 
  OSErr
  ThreadBeginCritical(void);
 
  OSErr
  ThreadEndCritical(void);
 
  OSErr
  GetThreadCurrentTaskRef(ThreadTaskRef *threadTRef);
 
  OSErr
  GetThreadStateGivenTaskRef(ThreadTaskRef threadTRef, ThreadID threadToGet,
                             ThreadState *threadState);
 
  OSErr
  SetThreadReadyGivenTaskRef(ThreadTaskRef threadTRef, ThreadID threadToSet);
 
#if PRAGMA_STRUCT_ALIGN
#pragma options align = reset
#elif PRAGMA_STRUCT_PACKPUSH
#pragma pack(pop)
#elif PRAGMA_STRUCT_PACK
#pragma pack()
#endif
 
#ifdef PRAGMA_IMPORT_OFF
#pragma import off
#elif PRAGMA_IMPORT
#pragma import reset
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif /* __THREADS__ */