/***********************************************************************
Filename   : rvthread.h
Description: rvthread header file
************************************************************************
      Copyright (c) 2001,2002 RADVISION Inc. and RADVISION Ltd.
************************************************************************
NOTICE:
This document contains information that is confidential and proprietary
to RADVISION Inc. and RADVISION Ltd.. No part of this document may be
reproduced in any form whatsoever without written prior approval by
RADVISION Inc. or RADVISION Ltd..

RADVISION Inc. and RADVISION Ltd. reserve the right to revise this
publication and make changes without obligation to notify any person of
such revisions or changes.
***********************************************************************/
/*$
{package:
    {name: Thread}
    {superpackage: CCore}
    {include: rvthread.h}
    {description:
        {p: This module provides functions for creating and manipulating threads.}
        {p: Threads need to be constructed, created, and then started. Between being
            constructed and created, parameters such as stack size and special attributes
            may be set. The only parameter that may be changed after creating a thread is
            the priority.}
        {p: Pre-existing threads may use the RvThreadConstructFromUserThread function to
            create a thread handle so that thread specific variables and other functions
            which require a thread handle can be used. Since these threads are already
            running, attributes of these threads can not be changed and some OS's do not
            even allow the priority to be changed. Destructing a thread created in this
            manner does not delete the thread itself, it just returns it to the state
            it was in when RvThreadConstructFromUserThread was called. In addition
            RvThreadDestruct MUST be called before such a thread is allowed to exit.}
        {p: Functions which don't require a thread handle (except RvThreadCurrent) may
            be called from any thread, even if a handle was not constructed.}
    }
}
$*/
#ifndef RV_THREAD_H
#define RV_THREAD_H

#include "rvccore.h"
#include "rvlock.h"
#include "rvsemaphore.h"
#include "rvtime.h"

/* Error checks to make sure configuration has been done properly */
#if !defined(RV_THREAD_TYPE) || ((RV_THREAD_TYPE != RV_THREAD_POSIX) && \
    (RV_THREAD_TYPE != RV_THREAD_SOLARIS) && (RV_THREAD_TYPE != RV_THREAD_VXWORKS) && \
    (RV_THREAD_TYPE != RV_THREAD_PSOS) && (RV_THREAD_TYPE != RV_THREAD_OSE) && \
    (RV_THREAD_TYPE != RV_THREAD_NUCLEUS) && (RV_THREAD_TYPE != RV_THREAD_WIN32) && \
    (RV_THREAD_TYPE != RV_THREAD_WINCE) && (RV_THREAD_TYPE != RV_THREAD_UNIXWARE) && \
    (RV_THREAD_TYPE != RV_THREAD_NONE))
#error RV_THREAD_TYPE not set properly
#endif


#if (RV_THREAD_TYPE != RV_THREAD_NONE)

#if !defined(RV_THREAD_PRIORITY_DEFAULT)
#error RV_THREAD_PRIORITY_DEFAULT not set properly
#endif

#if !defined(RV_THREAD_STACKSIZE_DEFAULT)
#error RV_THREAD_STACKSIZE_DEFAULT not set properly
#endif

#if !defined(RV_THREAD_STACKSIZE_USEDEFAULT)
#error RV_THREAD_STACKSIZE_USEDEFAULT not set properly
#endif

#if !defined(RV_THREAD_ATTRIBUTE_DEFAULT)
#error RV_THREAD_ATTRIBUTE_DEFAULT not set properly
#endif

#if !defined(RV_THREAD_MAX_NAMESIZE) || (RV_THREAD_MAX_NAMESIZE < 1)
#error RV_THREAD_MAX_NAMESIZE not set properly
#endif

#if !defined(RV_THREAD_MAX_VARS) || (RV_THREAD_MAX_VARS < 1)
#error RV_THREAD_MAX_VARS not set properly
#endif

#if !defined(RV_THREAD_MAX_VARNAMESIZE) || (RV_THREAD_MAX_VARNAMESIZE < 1)
#error RV_THREAD_MAX_VARNAMESIZE not set properly
#endif

#endif /* (RV_THREAD_TYPE != RV_THREAD_NONE) */

/* End of configuration error checks */

/* Module specific error codes (-512..-1023). See rverror.h dor more details */
#define RV_THREAD_ERROR_RUNNING -512 /* Thead is running and cannot be destructed or started */
#define RV_THREAD_ERROR_NOTSTARTED -513 /* Thead has never been started */
#define RV_THREAD_ERROR_CREATED -514 /* Thread has already been created */
#define RV_THREAD_ERROR_NOTCREATED -515 /* Thread has not been created */
#define RV_THREAD_ERROR_DESTRUCTING -516 /* Another thread is already destructing this one */
#define RV_THREAD_ERROR_NOVARS -517 /* No more thread specific variable available */
#define RV_THREAD_ERROR_BADTHREAD -518 /* Current thread never constructed */
#define RV_THREAD_ERROR_USERAPP -519 /* Operation not allowed on user application thread */

/* Module specific Warning codes (512..1023). See rverror.h for more details */
#define RV_THREAD_WARNING_NOTFOUND 512 /* Variable find operation did not find a match */

/*$
{type:
    {name: RvThreadId}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: An OS specific thread ID. Used to identify threads regardless
            of whether or not a thread handle has been constructed for it.}
    }
}
$*/
/*$
{type:
    {name: RvThreadAttr}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: OS specific attributes and options used for threads. See definitions in rvthread.h
            along with the default values in rvccoreconfig.h for more information.}
    }
}
$*/
/* Get include files and define types for each OS. RvThreadId, */
/* RvThreadAttr, and RvThreadBlock need to be defined along */
/* with priority range and direction. RvThreadBlock is only used */
/* internally. */
#if (RV_THREAD_TYPE == RV_THREAD_NONE)
typedef RvInt RvThreadBlock;
typedef RvInt RvThreadId;
typedef struct
{
    RvInt unused;
} RvThreadAttr;
#endif

#if (RV_THREAD_TYPE == RV_THREAD_POSIX) || (RV_THREAD_TYPE == RV_THREAD_SOLARIS) || \
    (RV_THREAD_TYPE == RV_THREAD_UNIXWARE)
#include <pthread.h>
typedef pthread_attr_t RvThreadBlock; /* We use block for attributes since we don't want them touched directly */
typedef pthread_t RvThreadId;
typedef struct {
    /* These correspond to attributes in the pthread_attr struct that we let users set */
    int contentionscope;
    int policy;
    int inheritsched;
#if (RV_THREAD_TYPE == RV_THREAD_SOLARIS)
    size_t guardsize; /* Solaris extention to standard attributes (use (size_t)(-1) for default*/
#endif
} RvThreadAttr;
#define RV_THREAD_PRIORITY_MAX 0
#define RV_THREAD_PRIORITY_MIN 20
#define RV_THREAD_PRIORITY_INCREMENT (-1)
#endif

#if (RV_THREAD_TYPE == RV_THREAD_VXWORKS)
#include <vxworks.h>
#include <taskLib.h>
typedef WIND_TCB RvThreadBlock;
typedef int RvThreadId;
typedef int RvThreadAttr; /* options parameter to taskInit */
#define RV_THREAD_PRIORITY_MAX 2
#define RV_THREAD_PRIORITY_MIN 254
#define RV_THREAD_PRIORITY_INCREMENT (-1)
#endif

#if (RV_THREAD_TYPE == RV_THREAD_PSOS)
#include <psos.h>
typedef unsigned long RvThreadId;
typedef struct {
    unsigned long flags; /* t_create flags */
    unsigned long mode;  /* t_start mode */
    unsigned long tslice; /* tslice for t_tslice */
} RvThreadAttr;
#if (RV_OS_VERSION == RV_OS_PSOS_2_0)
typedef void* RvThreadBlock;
#else
/* Diab tool - for PowerPC */
typedef struct tinfo RvThreadBlock; /* pSOS doesn't give any access to actual TCB */
#endif
#define RV_THREAD_PRIORITY_MAX 240
#define RV_THREAD_PRIORITY_MIN 1
#define RV_THREAD_PRIORITY_INCREMENT 1
#endif

#if (RV_THREAD_TYPE == RV_THREAD_OSE)
#include <ose.h>
typedef PROCESS *RvThreadBlock;
typedef PROCESS RvThreadId;
typedef struct { /* parameters for create_process */
    enum PROCESS_TYPE proc_type;
    OSTIME timeslice;
    PROCESS block;
    struct OS_redir_entry *redir_table;
    OSVECTOR vector;
    OSUSER user;
} RvThreadAttr;
#define RV_THREAD_PRIORITY_MAX 1
#define RV_THREAD_PRIORITY_MIN 31
#define RV_THREAD_PRIORITY_INCREMENT (-1)
#endif

#if (RV_THREAD_TYPE == RV_THREAD_NUCLEUS)
#include <nucleus.h>
typedef NU_TASK RvThreadBlock;
typedef NU_TASK *RvThreadId;
typedef struct { /* parameters for NU_Create_task */
    UNSIGNED time_slice;
    OPTION preempt;
} RvThreadAttr;
#define RV_THREAD_PRIORITY_MAX 4
#define RV_THREAD_PRIORITY_MIN 255
#define RV_THREAD_PRIORITY_INCREMENT (-1)
#endif

#if (RV_THREAD_TYPE == RV_THREAD_WIN32) || (RV_THREAD_TYPE == RV_THREAD_WINCE)
#include <windows.h>
typedef HANDLE RvThreadBlock; /* use the tcb as the handle reference */
typedef DWORD RvThreadId;
typedef struct {
    BOOL disablepriorityboost; /* value for SetThreadPriorityBoost (Win NT 4.0 or newer only) */
    DWORD affinitymask;        /* value for SetThreadAffinityMask */
    DWORD idealprocessor;      /* value for SetThreadIdealProcessor (Win NT 4.0 or newer only) */
} RvThreadAttr;
#define RV_THREAD_PRIORITY_MAX 2
#define RV_THREAD_PRIORITY_MIN (-2)
#define RV_THREAD_PRIORITY_INCREMENT 1
#endif

/* Forward declaration */
typedef struct RvThread_s RvThread;

/*$
{callback:
    {name: RvThreadFunc}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: This is the function that should be called as the main function of a thread.}
    }
    {proto: void RvThreadFunc(RvThread *th, void *data);}
    {params:
        {param: {n: th} {d: Pointer to the thread structure of the current thread.}}
        {param: {n: data} {d: User parameter that was passed to RvThreadConstruct.}}
    }
}
$*/
typedef void (*RvThreadFunc)(RvThread *, void *);

/*$
{callback:
    {name: RvThreadVarFunc}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: This callback is called when a thread which has a thread specific variable
            associated with it exits. This callback is set when creating the thread
            specific variable.}
    }
    {proto: RvStatus RvThreadVarFunc(RvThread *th, void *data, RvUint32 index);}
    {params:
        {param: {n: th} {d: Pointer to the thread structure of the current thread.}}
        {param: {n: data} {d: The current value of the thread specific variable for this thread.}}
        {param: {n: index} {d: The index of the thread specific variable itself.}}
    }
    {notes:
        {note:  The callback will execute within thread that is exiting.}
        {note:  For threads constructed with RvThreadConstructFromUserThread, the callback will
                actually occur when the thread calls RvThreadDestruct.}
        {note:  The callback function may not make calls to RvThreadConstruct, RvThreadDestruct,
                RvThreadConstructFromUserThread, RvThreadCreateVar, or RvThreadDeleteVar.}
    }
}
$*/
typedef void (*RvThreadVarFunc)(RvThread *, void *, RvUint32 index);

/*$
{type: