ThreadAttachToQueue()

void	ThreadAttachToQueue(
        QueueHandle		qh,				/* queue to attach */
        ClassStruct		* class);				/* primary class of thread */

This routine attaches the calling thread to the passed event queue. This is used only for event-driven threads. Typically, this routine is called when a thread is created; attaching to queues is automatic in nearly all cases, and you will rarely need this routine.

Pass the handle of the queue in qh and a class pointer in class . The class will be attached to the event queue and will handle all messages sent directly to the thread. This class should nearly always be a subclass of ProcessClass .

If a queue handle of zero is passed, the thread wants to "reattach" to the current queue. This is used typically during shutdown of event-driven threads, and it is nearly always taken care of automatically by ProcessClass .

Include: thread.h

ThreadCreate()

ThreadHandle ThreadCreate(
        word	priority,			/* Initial base priority of new thread */
        word	valueToPass,			/* Optional data to pass to new thread */
        word	(*startRoutine)(word valuePassed),
				/* Pointer to entry routine */

        word	stackSize,			/* Size of the stack for the new thread */
        GeodeHandle owner);				/* Geode that will own the new thread */

This routine creates a new procedural thread for a process. If you need a new event-driven thread, send MSG_PROCESS_CREATE_EVENT_THREAD to your process object instead.

Pass the following parameters to this routine:

priority: The priority of the new thread. Typically this will be one of the standard thread priorities (see below).
valueToPass: A word of optional data to be passed to the entry routine of the new thread. This can be used, for example, to indicate the thread's initial context or for initializing thread variables.
startRoutine: A pointer to the entry routine to be executed immediately for the thread. This may be in either fixed or movable memory. The segment must be a virtual segment. Note that if the routine is in movable memory, it may degrade heap performance for the life of the thread (its movable block will remain locked for extended stretches of time). The routine may return the thread's exit code or may call ThreadDestroy() directly.
stackSize: The stack size allocated for the thread. 512 bytes is typically enough for threads doing neither UI nor file system work; threads working with the file system will require 1 K. Threads working with UI objects will require 3 K.
owner: The geode handle of the geode that will own the thread. If the calling thread's geode will own the new thread, it can call GeodeGetProcessHandle() prior to calling ThreadCreate() .

ThreadCreate() returns the thread handle of the new thread. If an error occurs, the calling thread's error code will be set and a null handle returned; you should likely call ThreadGetError() to retrieve the error code after creating the new thread. A return of NO_ERROR_RETURNED from ThreadGetError() means no error occurred.

The standard thread priorities that may be passed in the priority parameter are listed below:

PRIORITY_TIME_CRITICAL: The highest priority of all; you should not use this in general because it will pre-empt nearly all other threads. (It may be useful, however, during debugging.)
PRIORITY_HIGH: A high priority; generally only used for highly important threads.
PRIORITY_UI: Another high priority; this is used for User Interface threads to provide quick response to user actions.
PRIORITY_FOCUS: A medium-level priority; this is used for whatever thread has the current input focus (whichever thread the user is currently working with).
PRIORITY_STANDARD: The standard application thread priority; you should typically use this when creating new threads.
PRIORITY_LOW: A low priority for tasks that can be done in the background.
PRIORITY_LOWEST: The lowest standard priority; it is used for threads that can take any amount of time to complete.

Include: thread.h

ThreadDestroy()

void	ThreadDestroy(
        word	errorCode,	/* Error code to indicate cause of destruction */
        optr	ackObject,	/* Object to receive destruction acknowledgment */
        word	ackData);	/* Additional word of data to pass (as the low
			 * word of optr for source of MSG_META_ACK) */

This routine causes the current (calling) thread to exit and then destroy itself. The thread is responsible for ensuring that it has no leftover resources allocated or semaphores locked.

Pass it an error code or exit code meaningful to the application and the other threads in the application. This error code will be used by the debugger to determine the cause of the thread's exit; a null error code usually indicates successful completion of the thread's task.

Pass also the optr of the object to receive acknowledgement of the thread's destruction. The object specified will receive MSG_META_ACK after the calling thread is completely destroyed.

Be Sure To: Always clean up before exiting a thread. Unlock locked resources, free allocated memory, etc. You do not have to do these things for the application's primary thread; the process object (the primary thread) will automatically clean up after itself.

Include: thread.h

ThreadFreeSem()

void	ThreadFreeSem(
        SemaphoreHandle sem);			/* semaphore to be freed */

This routine frees the specified semaphore that had been allocated with ThreadAllocSem() . You must be sure that no threads are using the semaphore or will use it after it has been freed. Subsequent access attempts could cause illegal handle errors or worse.

Include: sem.h

See Also: ThreadAllocSem(), ThreadPSem(), ThreadVSem(), ThreadPTimedSem().

ThreadAttachToQueue()

ThreadCreate()

ThreadDestroy()

ThreadFreeSem()

ThreadFreeThreadLock()