The Process Object

ProcessClass implements all the functionality for creating and managing the process aspect of a geode. It creates the process thread and associated message queues. ProcessClass is a subclass of MetaClass and is the superclass of GenProcessClass , below. You will probably not use ProcessClass directly, but you will almost certainly use GenProcessClass .

ProcessClass has no instance data fields of its own. The messages defined by it are listed below:

MSG_PROCESS_NOTIFY_PROCESS_EXIT

void	MSG_PROCESS_NOTIFY_PROCESS_EXIT(
        GeodeHandle 		exitProcess,
        word		exitCode);

This is sent to a Process object when one of its child processes exits. Many types of processes do not need to know when a child process exists; these processes need not handle this message.

Source: Kernel

Destination: Process of creating geode of child process exiting.

Parameters: This message is provided as notification only, i.e. there is no default handling of it. May be intercepted as desired.

Parameters: exitProcess Child process that exited.

exitCode

Exit code. May be an error code.

Return: Nothing.

MSG_PROCESS_NOTIFY_THREAD_EXIT

void	MSG_PROCESS_NOTIFY_THREAD_EXIT(
        ThreadHandle		exitProcess,
        word		exitCode);

This message is sent to a Process object when a thread owned by it (via the ThreadCreate() routine) exits.

Source: Kernel.

Destination: Process owning thread which is exiting.

Interception: This message is provided as notification only (i.e. there is no default handling of it). May be intercepted as desired.

Parameters: exitProcess Handle of thread that exited.

exitCode

Exit code (may be an error code).

Return: Nothing.

MSG_PROCESS_MEM_FULL

void	MSG_PROCESS_MEM_FULL(
        word 	type);

This message is sent to a Process object by the memory manager when the heap is getting full. A Process object receiving this message should try to free memory (or mark it discardable) if possible.

Source: Kernel's heap manager.

Destination: All processes.

Interception: Any process which can adjust the amount of memory that it is using should respond to this message by reducing its demands on the system heap. For instance, buffers or UI object trees kept purely for performance reasons could be freed or reduced in number.

Parameters: type HeapCongestion .

Return: Nothing.

Structures:

  typedef enum {

	/* HC_SCRUBBING: 
	 * Heap is being scrubbed. */
	HC_SCRUBBING,

	/* HC_CONGESTED:
	 * Scrubber couldn't free a satisfactory 
	 * amount of memory. */
	HC_CONGESTED,

	/* HC_DESPERATE:
	 * Heap is perilously close to overflowing. */
	HC_DESPERATE

} HeapCongestion;

MSG_PROCESS_CREATE_UI_THREAD

Boolean	MSG_PROCESS_CREATE_UI_THREAD(
        ThreadHandle		*newThread,
        ClassStruct 		*class,
        word 		stackSize);

This is a low-level utility message requesting that the process create the UI thread for an application. Does nothing more than MSG_PROCESS_CREATE_EVENT_THREAD , but is split out to allow for interception or to change class or stack size.

Source: First thread of application process if geode has one or more resources marked as "ui-object" blocks.

Destination: First thread of application process.

Interception: May be intercepted to change class or stack size before calling superclass, or to replace default handling completely.

Parameters: newThread Pointer to a ThreadHandle buffer to store the created thread handle.

class

Object class for the new thread. If you don't have any special messages to handle in this thread, besides those intended for objects run by the thread, you can just specify ProcessClass as the object class.

stackSize

Stack size for the new thread (3K bytes is probably reasonable).

Return: true if the thread was not created because of some problem.

Warnings: Be careful of deadlock situations.

MSG_PROCESS_CREATE_EVENT_THREAD

Boolean	MSG_PROCESS_CREATE_EVENT_THREAD(
        ThreadHandle		*newThread
        ClassStruct 		*class,
        word		stackSize);

This message is a utility that creates a new event-driven thread owned by the recipient Process object. Typically, a Process object will send this message to itself when it needs an additional event thread. (It cannot be used to create a non-event driven thread. Use ThreadCreate() for this purpose instead.) This is implemented at ProcessClass and takes care of all the details of creating a new event-driven thread. The thread will always receive a MSG_META_ATTACH as its first event.

Source: Unrestricted.

Destination: Any process. This process will own the thread.

Interception: Not necessary, as the default handler provides the message's utility.

Parameters: newThread Pointer to a ThreadHandle buffer to store the created thread handle.

class

Object class for the new thread. If you don't have any special messages to handle in this thread besides those intended for objects run by the thread, you can just specify ProcessClass as the object class.

stackSize

Stack size for the new thread. 512 bytes is probably reasonable. If the thread will be running any objects that can undergo keyboard navigation (like dialog boxes and triggers and so forth), you'll probably want to make it 1K. The kernel already adds some extra space for handling interrupts (about 100 bytes).

Return: true if the thread was not created because of some problem.

Warnings: Be careful of deadlock situations.