rvthread.h

基于h323协议的软phone

    {name: RvThread}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: A thread object.}
    }
}
$*/
/* Typedef of RvThread is above. */
struct RvThread_s {
    RvInt32 state;                        /* Current thread state */
    RvChar name[RV_THREAD_MAX_NAMESIZE];  /* Full name of thread */
    void *stackaddr;                      /* pointer to memory for thread's stack space */
    void *stackstart;                     /* actual pointer to start of stack (told to OS) */
    RvInt32 reqstacksize;                 /* requested size of stack */
    RvInt32 realstacksize;                /* size of stack told to the OS (starting at stackstart) */
    RvInt32 stacksize;                    /* actual size of stack memory (pointed to by stackaddr) */
    RvBool stackallocated;                /* set to RvTrue if stack was allocated internally */
    RvBool waitdestruct;                  /* set to RvTrue if destruct is waiting for thread to exit */
    RvLock datalock;                      /* lock for access to thread structure */
    RvSemaphore exitsignal;               /* used to signal thread completion */
    RvThreadFunc func;                    /* function to call in thread */
    void *data;                           /* data parameter to be passed to func */
    RvInt32 priority;                     /* priority of thread */
    RvThreadAttr attr;                    /* OS specific thread attributes */
    RvThreadId id;                        /* OS id of thread */
    RvThreadBlock tcb;                    /* OS specific task control block or pointer to it */
    RvBool autodelete;                    /* Are we automatically deleting this thread if we found out it was stopped? Default is RV_FALSE */
    void *vars[RV_THREAD_MAX_VARS];       /* Values of thread specific variables */
};

#if defined(__cplusplus)
extern "C" {
#endif

/* Prototypes: See documentation blocks below for details. */
RvStatus RvThreadInit(void);
RvStatus RvThreadEnd(void);
RVCOREAPI RvStatus RVCALLCONV RvThreadConstruct(RvThread *th, RvThreadFunc func, void *data);
RVCOREAPI RvStatus RVCALLCONV RvThreadConstructFromUserThread(RvThread *th);
RVCOREAPI RvStatus RVCALLCONV RvThreadDestruct(RvThread *th);
RVCOREAPI RvStatus RVCALLCONV RvThreadCreate(RvThread *th);
RVCOREAPI RvStatus RVCALLCONV RvThreadStart(RvThread *th);
RVCOREAPI RvThread * RVCALLCONV RvThreadCurrent(void);
RVCOREAPI RvThreadId RVCALLCONV RvThreadCurrentId(void);
RVCOREAPI RvBool RVCALLCONV RvThreadIdEqual(RvThreadId id1, RvThreadId id2);
RVCOREAPI RvStatus RVCALLCONV RvThreadSleep(const RvTime *t);
RVCOREAPI RvStatus RVCALLCONV RvThreadNanosleep(RvInt64 nsec);
RVCOREAPI RvStatus RVCALLCONV RvThreadGetOsName(RvThreadId id, RvChar *buf, RvInt32 size);
RVCOREAPI RvChar * RVCALLCONV RvThreadGetName(RvThread *th);
RVCOREAPI RvStatus RVCALLCONV RvThreadSetName(RvThread *th, const RvChar *name);
RVCOREAPI RvStatus RVCALLCONV RvThreadSetAutoDelete(RvThread *th, RvBool autoDelete);
RVCOREAPI RvStatus RVCALLCONV RvThreadSetStack(RvThread *th, void *stackaddr, RvInt32 stacksize);
RVCOREAPI RvStatus RVCALLCONV RvThreadSetPriority(RvThread *th, RvInt32 priority);
RVCOREAPI RvStatus RVCALLCONV RvThreadGetAttr(RvThread *th, RvThreadAttr *attr);
RVCOREAPI RvStatus RVCALLCONV RvThreadSetAttr(RvThread *th, const RvThreadAttr *attr);
RVCOREAPI RvStatus RVCALLCONV RvThreadCreateVar(RvThreadVarFunc exitfunc, RvChar *name, RvUint32 *index);
RVCOREAPI RvStatus RVCALLCONV RvThreadDeleteVar(RvUint32 index);
RVCOREAPI RvStatus RVCALLCONV RvThreadSetVar(RvUint32 index, void *value);
RVCOREAPI RvStatus RVCALLCONV RvThreadGetVar(RvUint32 index, void **value);
RVCOREAPI RvStatus RVCALLCONV RvThreadFindVar(RvChar *name, RvUint32 *index);

#if defined(RV_TEST_CODE)
void RvThreadTest(void);
#endif /* RV_TEST_CODE */

#if defined(__cplusplus)
}
#endif

/* Function Documentation */
/*$
{function scope="protected":
    {name: RvThreadInit}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: Initializes the Thread module. Must be called once (and
            only once) before any other functions in the module are called.}
    }
    {proto: RvStatus RvThreadInit(void); }
    {returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function scope="protected":
    {name: RvThreadEnd}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: Shuts down the Thread module. Must be called once (and
            only once) when no further calls to this module will be made.}
    }
    {proto: RvStatus RvThreadEnd(void); }
    {returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
    {name: RvThreadConstruct}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: Constructs a thread object. No actual thread is created yet. All settings
            for this thread use the defaults defined in rvccoreconfig.h so that it is
            not necessary to set every parameter if the default ones are acceptable for
            this thread.}
    }
    {proto: RvStatus RvThreadConstruct(RvThread *th, RvThreadFunc func, void *data);}
    {params:
        {param: {n: th} {d: Pointer to thread object to be constructed.}}
        {param: {n: func} {d: Pointer to function which will excued in the new thread.}}
        {param: {n: data} {d: User defined data which will be passed to func when it is executed.}}
    }
    {returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
    {name: RvThreadConstructFromUserThread}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: Constructs a thread object and associates it with an existing thread that
            was created externally (not using RvThreadConstruct). It should be called
            from the thread itself. Threads which have made this call must call
            RvThreadDestruct before exiting.}
    }
    {proto: RvStatus RvThreadConstructFromUserThread(RvThread *th);}
    {params:
        {param: {n: th} {d: Pointer to thread object to be constructed.}}
    }
    {returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
    {name: RvThreadDestruct}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: Destruct a thread object. Threads can not be destructed until they have
            exited so if the thread has not exited this function will wait until
            it does before returning.}
        {p: Threads created with RvThreadConstructFromUserThread are a special case
            where RvThreadDestruct MUST be called from the thread itself before
            exiting (and obviously won't wait for the thread to exit).}
    }
    {proto: RvStatus RvThreadDestruct(RvThread *th);}
    {params:
        {param: {n: th} {d: Pointer to thread object to be destructed.}}
    }
    {returns: RV_OK if successful otherwise an error code.}
    {notes:
        {note:  RvThreadDestruct may only be called once on each thread. Thus
                it may not be called simultaneously from multiple threads (with the
                same thread to destruct).}
    }
}
$*/
/*$
{function:
    {name: RvThreadCreate}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: Create the actual thread. The thread will be created by the OS and
            allocate all needed resources but will not begin executing.}
    }
    {proto: RvStatus RvThreadCreate(RvThread *th);}
    {params:
        {param: {n: th} {d: Pointer to thread object to be created.}}
    }
    {returns: RV_OK if successful otherwise an error code.}
    {notes:
        {note:  Some operating systems do not allow threads to be started in the
                suspended state so the physical thread will not appear until
                RvThreadStart is called.}
        {note:  If the call fails, RvThreadDestruct should be called in order
                to properly clean up.}
    }
}
$*/
/*$
{function:
    {name: RvThreadStart}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: Start thread execution.}
    }
    {proto: RvStatus RvThreadStart(RvThread *th);}
    {params:
        {param: {n: th} {d: Pointer to thread object to be started.}}
    }
    {returns: RV_OK if successful otherwise an error code.}
    {notes:
        {note:  If the call fails, RvThreadDestruct should be called in order
                to properly clean up.}
    }
}
$*/
/*$
{function:
    {name: RvThreadCurrent}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: Get the thread handle of the current thread.}
    }
    {proto: RvThread *RvThreadCurrent(void);}
    {returns: A pointer to the thread object of the current thread.}
    {notes:
        {note:  If the thread was not created with this Thread module or was
                not attach to a thread object with RvThreadConstructFromUserThread
                then this function will return NULL.}
    }
}
$*/
/*$
{function:
    {name: RvThreadCurrentId}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: Get the OS specific thread ID of the current thread.}
    }
    {proto: RvThreadId RvThreadCurrentId(void);}
    {returns: The thread ID of the current thread.}
    {notes:
        {note:  This works for all threads regardless of how they were created.}
    }
}
$*/
/*$
{function:
    {name: RvThreadIdEqual}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: Compares two thread IDs.}
    }
    {proto: RvBool RvThreadIdEqual(RvThreadId id1, RvThreadId id2);}
    {params:
        {param: {n: id1} {d: Thread ID.}}
        {param: {n: id2} {d: Thread ID.}}
    }
    {returns: RV_TRUE if threads are the same, otherwise RV_FALSE.}
}
$*/
/*$
{function:
    {name: RvThreadSleep}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: Suspends the current thread for the requested amount of time.}
    }
    {proto: RvStatus RvThreadSleep(RvTime *t);}
    {params:
        {param: {n: t} {d: Pointer to RvTime structure containing amount of time to sleep.}}
    }
    {returns: RV_OK if successful otherwise an error code.}
    {notes:
        {note:  This works for all threads regardless of how they were created.}
        {note:  The exact time of suspension is based on the operating system and the
                resolution of the system clock.}
    }
}
$*/
/*$
{function:
    {name: RvThreadNanosleep}
    {superpackage: Thread}
    {include: rvthread.h}
    {description:
        {p: Suspends the current thread for the requested amount of time.}
    }
    {proto: RvStatus RvThreadNanosleep(RvInt64 nsecs);}
    {params:
        {param: {n: nsecs} {d: Time to sleep in nanoseconds.}}
    }
    {returns: RV_OK if successful otherwise an error code.}