#ifndef AEETHREAD_H
#define AEETHREAD_H /* #ifndef AEETHREAD_H */
/*=====================================================

FILE:  AEEThread.h

SERVICES:  
        user-level threads

GENERAL DESCRIPTION:
        interface definition for a cooperatively-scheduled threads 
        implementation

=====================================================

      Copyright © 1999-2002 QUALCOMM Incorporated 
              All Rights Reserved.
           QUALCOMM Proprietary/GTDR

=====================================================*/

#include "AEE.h"
#include "AEERscPool.h"

typedef struct IThread IThread;

/*
  ---- IThread start function type 
*/
typedef int (*PFNTHREAD)(IThread *piThread, void *pvCxt);

#define INHERIT_IThread(iname)\
   INHERIT_IRscPool(iname);\
   int          (*Start)        (iname *p, int nStackSz, \
                                 PFNTHREAD pfStart, void *pvStart);\
   int          (*Exit)         (iname *p, int nRv);\
   void         (*Join)         (iname *p, AEECallback *pcb, int *pnRv);\
   void         (*Suspend)      (iname *p);\
   AEECallback *(*GetResumeCBK) (iname *p)


/*
  ---- IThread interface def
*/
AEEINTERFACE(IThread) {
   INHERIT_IThread(IThread);
};



#define ITHREAD_AddRef(p)             AEEGETPVTBL((p),IThread)->AddRef((p))
#define ITHREAD_Release(p)            AEEGETPVTBL((p),IThread)->Release((p))
#define ITHREAD_QueryInterface(p,i,o) AEEGETPVTBL((p),IThread)->QueryInterface((p),(i),(o))

#define ITHREAD_Malloc(p,s)           AEEGETPVTBL((p),IThread)->Malloc((p),(s))
#define ITHREAD_Free(p,m)             AEEGETPVTBL((p),IThread)->Free((p),(m))
#define ITHREAD_HoldRsc(p,r)     AEEGETPVTBL((p),IThread)->HoldRsc((p),(r))   
#define ITHREAD_ReleaseRsc(p,r)  AEEGETPVTBL((p),IThread)->ReleaseRsc((p),(r))
#define ITHREAD_Start(p,s,f,x)   AEEGETPVTBL((p),IThread)->Start((p),(s),(f),(x)) 
#define ITHREAD_Exit(p,r)        AEEGETPVTBL((p),IThread)->Exit((p),(r))      
#define ITHREAD_Join(p,cb,r)     AEEGETPVTBL((p),IThread)->Join((p),(cb),(r))   
#define ITHREAD_Suspend(p)       AEEGETPVTBL((p),IThread)->Suspend((p))     
#define ITHREAD_GetResumeCBK(p)  AEEGETPVTBL((p),IThread)->GetResumeCBK((p))

#define ITHREAD_Stop(p) ITHREAD_Exit((p),-1) /* presumably don't care about thread 
                                                return value, use -1... */


/*
======================================================================= 
  DATA STRUCTURE DOCUMENTATION
=======================================================================

=======================================================================

PFNTHREAD

Description:
   Prototype of a thread start function, the first function a new 
   AEEThread calls

Definition:
   typedef int (*PFNTHREAD)(IThread *piThread, void *pvCxt);

Parameters:
  IThread *piThread: the current thread, the thread that's starting

  void *pvCxt: user data, the context passed to ITHREAD_Start

Return Value:
   thread's return value, collect with ITHREAD_Join()

Comments:
  when this function returns, any callback waiting for the thread to 
  finish is Resumed

See Also:
  ITHREAD_Start, ITHREAD_Join


======================================================================= 
  INTERFACES   DOCUMENTATION
======================================================================= 

Interface Name: IThread

Description: 
   IThread is a cooperatively-scheduled thread that layers over BREW's 
   callback-based APIs.  It exports methods to start and stop threads 
   and the methods necessary to implement blocking APIs given an 
   arbitrary callback-based API.

   IThreads are not re-useable, i.e. _Start() may only be called once, 
   and after a thread returns from its start function, after _Exit() 
   or after _Stop() is called, it may *not* re - _Start()ed.

======================================================================= 

Function: ITHREAD_Start()

Description: 
   This kicks off execution of an IThread

Prototype:

   int ITHREAD_Start(IThread *p, int nStackSz, 
                     PFNTHREAD pfStart, void *pvStart)

Parameters:
   IThread *p: Pointer to the IThread
   int nStackSz: number of bytes to allocate for the IThread's stack
   PFNTHREAD pfStart: the IThread start function, what'll be called when the
                         IThread begins execution
   void *pvStart: the argument to the IThread start function
   
Return Value:
   SUCCESS    if everything's ok
   EALREADY   if _Start() has already been called
   ENOMEMORY  if the stack size requested could not be allocated

Comments:  
   nStackSz should be specified as low as possible to accomodate the 
     IThread's start function and its user-level descendants.
     Additional stack bytes will be allocated for system calls.

Side Effects: 
   None

Version:
   Introduced BREW Client 3.0

See Also:
   ITHREAD_Exit()
   ITHREAD_Stop()

======================================================================= 

Function: ITHREAD_Exit()


Description: 
   Both  ITHREAD_Exit() and ITHREAD_Stop() end an IThread's execution, and set its return value.

Prototype:

   int ITHREAD_Exit(IThread *p, int nRv)

Parameters:
   IThread *p: Pointer to the IThread
   int nRv: the IThread's return value. This is used when the Callbacks registered via 
   _Join are resumed.
   
Return Value:
   SUCCESS  if everything's ok
   EFAILED  if the IThread's never been _Start()ed
   EALREADY if the IThread is already stopped

Comments:
   This method may be called from inside or outside the thread.
   If this method is called from within the thread, it doesn't return, 
      execution of the thread stops
   _Stop() sets the return value to -1, it is typically called from 
      outside the thread, when the caller doesn't care about return value

Side Effects: 
   All callbacks registered via _Join() are resumed

Version:
   Introduced BREW Client 3.0

See Also:
   ITHREAD_HoldRsc, ITHREAD_ReleaseRsc

======================================================================= 
Function: ITHREAD_Stop()
This function is the same as  ITHREAD_Exit().
======================================================================= 
Function: ITHREAD_Join()

Description: 
   Schedules a callback to fire when an IThread's execution ends, 
     collecting the return value in pnRv.

Prototype:

   void ITHREAD_Join(IThread *p, AEECallback *pcb, int *pnRv)

Parameters:
   IThread *p: Pointer to the IThread
   AEECallback *pcb: where to call when the thread is done
   int *pnRv: pointer to be filled with the IThread's return value
   
Return Value:
   None

Comments:
   None

Side Effects: 
   None

Version:
   Introduced BREW Client 3.0

See Also:
   None

======================================================================= 

Function: ITHREAD_Malloc()

Description: 
   Allocates memory and associates it with the lifetime of an IThread

Prototype:

   void *ITHREAD_Malloc(IThread *p, unsigned uSize);

Parameters:
   IThread *p: Pointer to the IThread
   unsigned uSize: number of bytes to allocate
   
Return Value:
   fresh memory on success, 
   0 if memory could not be allocated, or if the IThread isn't running

Comments:
   None

Side Effects: 
   None

Version:
   Introduced BREW Client 3.0

See Also:
   ITHREAD_Free, ITHREAD_Start

======================================================================= 

Function: ITHREAD_Free()

Description: 
   de-associates a memory pointer with the lifetime of an IThread and
   frees it

Prototype:

   void ITHREAD_Free(IThread *p, void *p);

Parameters:
   IThread *p: Pointer to the IThread
   void *p: pointer to free
   
Return Value:
   None

Comments:
   The pointer p *must* have come from ITHREAD_Malloc()

Side Effects: 
   None

Version:
   Introduced BREW Client 3.0

See Also:
   ITHREAD_Malloc, ITHREAD_Start, ITHREAD_ReleaseRsc

======================================================================= 

Function: ITHREAD_HoldRsc()

Description: 
   Associates a generic IBASE pointer with the lifetime of an IThread

Prototype:

   int ITHREAD_HoldRsc(IThread *p, IBase *pResource);

Parameters:
   IThread *p: Pointer to the IThread
   IBase *pResource: thing to keep track of
   
Return Value:
   SUCCESS   if everything's cool
   ENOMEMORY if memory could not be allocated to hold the resource

Comments:
  IThread does not _AddRef() the IBase passed in, so don't _Release() it
     after calling _HoldRsc().

Side Effects: 
   None

Version:
   Introduced BREW Client 3.0

See Also:
   ITHREAD_Start, ITHREAD_ReleaseRsc()

======================================================================= 

Function: ITHREAD_ReleaseRsc()

Description: 
   De-associates a generic IBASE pointer with the lifetime of an IThread, 
    _Release()s the IBASE

Prototype:

   uint32 ITHREAD_ReleaseRsc(IThread *p, IBase *pResource);

Parameters:
   IThread *p: Pointer to the IThread
   IBase *pResource: thing to forget
   
Return Value:
   Value of -1 if the IBASE could not be found in the IThread's resource list, 
   otherwise, the return value of IBASE_Release() on the resource

Comments:
   None

Side Effects: 
   The IBase referenced is _Release()d, so don't _Release() it again

Version:
   Introduced BREW Client 3.0

See Also:
   ITHREAD_Start, ITHREAD_HoldRsc()

======================================================================= 

Function: ITHREAD_Suspend()

Description: 
   Pauses execution of the IThread, returns execution state to that of the
    "primordial" BREW thread.  Used for implementing/scheduling 
    blocking calls.

Prototype:

   void ITHREAD_Suspend(IThread *p)

Parameters:
   IThread *p: Pointer to the IThread
   
Return Value:
   None

Comments:
   This function must only be called from within the IThread, calling from 
     outside the IThread has no effect.

   To resume execution of the IThread, call ISHELL_Resume() on the IThread's 
     resume AEECallback (_ResumeCBK()) before calling _Suspend().

Side Effects: 
   None

Version:
   Introduced BREW Client 3.0

See Also:
   ITHREAD_GetResumeCBK

======================================================================= 

Function: ITHREAD_GetResumeCBK()

Description: 
   Returns an CALLBACK_Init()ialized AEECallback for resumption of the 
      IThread.

Prototype:

   AEECallback *ITHREAD_GetResumeCBK(IThread *p)

Parameters:
   IThread *p: Pointer to the IThread
   
Return Value:
   AEECallback for resumption of the IThread

Comments:
   Do not call CALLBACK_Init() on the resulting AEECallback, doing so will
     break the thread.

Side Effects: 
   None

Version:
   Introduced BREW Client 3.0

See Also:
   ITHREAD_Suspend

======================================================================= */



#endif /* #ifndef AEETHREAD_H */

