COMMENT @----------------------------------------------------------------------

	Copyright (c) GeoWorks 1989 -- All Rights Reserved

PROJECT:	PC GEOS
FILE:		Objects/processC.def

DECLARER:	Kernel

DESCRIPTION:
	This file defines ProcessClass

	$Id: processC.def,v 1.1 97/04/04 14:19:51 newdeal Exp $

------------------------------------------------------------------------------@

SetDef	__PROCESSC

include Objects/metaC.def

StartKernel

ProcessClass	class	MetaClass

;	COMMON FOR ALL EVENTS RECEIVED BY A PROCESS:
;
; Pass:		ds - dgroup
;		es - segment of process class (usually dgroup)
;		si - second word of output descriptor sent to ObjMessage
;		cx, dx, bp - standard method arguments
; Return:	ax, cx, dx, bp - possible return values (else can be destroyed)
;		bx, si, di, ds, es - can always be destroyed


MSG_PROCESS_NOTIFY_PROCESS_EXIT		message

; MSG_PROCESS_NOTIFY_PROCESS_EXIT is sent to a process when a process created
; by it (via the GeodeLoad routine) exits.  This is done by keeping a
; "GH_parentProcess" handle with each process.  Many types of processes do not
; need to know when a child process exits, these processes need not handle
; MSG_PROCESS_NOTIFY_PROCESS_EXIT.
;
; Context:	Process/Thread death mechanism
; Source:	Kernel
; Destination:	Process of creating geode of child process exiting
; Interception:	This message is provided as notification only, i.e. there is
;		no default handling of it.  May be intercepted as desired.
; Pass:		cx - handle of child process that exited
;		dx - exit code
; Return:	none
;		ax, cx, dx, bp - may be destroyed

MSG_PROCESS_NOTIFY_THREAD_EXIT		message

; MSG_PROCESS_NOTIFY_THREAD_EXIT is sent to a process when a thread owned by
; it (via the ThreadCreate routine) exits.
;
; Context:	Process/Thread death mechanism
; 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.
; Pass:		cx - handle of thread that exited
;		dx - exit code
; Return:	none
;		ax, cx, dx, bp - may be destroyed

MSG_PROCESS_MEM_FULL				message

; MSG_PROCESS_MEM_FULL is sent by the memory management system when the heap is
; getting full. A process receiving this event should free memory (or make it
; discardable) if possible.
;
; Context:	Heap performance optimization
; 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.
; Pass:		cx	= HeapCongestion describing how congested the heap
;			  is (see heap.def).
; Return:	none
;		ax, cx, dx, bp - may be destroyed

MSG_PROCESS_CREATE_UI_THREAD		message
;
; Low-level utility method to create the UI thread for an application.  Does
; nothing more than MSG_PROCESS_CREATE_EVENT_THREAD, but is split out to
; allow for interception, to change class, stack size, or potentially return
; an existing thread.
;
; Context:	Part of attach/startup mechanism
; Source:	First thread of application process, from within
;		default MSG_PROCESS_STARTUP_UI_THREAD handler, 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, stack size before calling
;		superclass, or to replace default handling completely.
; Pass:		cx:dx	- object class for the new thread
;			  If you don't have any special methods to handle in
;			  this thread, besides those intended for objects run
;			  by the thread, you can just specify ProcessClass as
;			  the object class.
; 		bp	- stack size to use for the new thread, or NULL
;			  for the default stack size
; Return:	carry clear if thread created:
;		ax	- handle of new thread
;		cx, dx, bp - destroyed
;

MSG_PROCESS_CREATE_EVENT_THREAD		message
;
; This is a utility method that one can send to oneself to create a new
; event-driven thread. It cannot be used to create a non-event-driven
; thread (use ThreadCreate instead). This is implemented at ProcessClass
; and takes care of all the cruft of creating a new event-driven thread.
; The thread will always receive a MSG_META_ATTACH as its first event.
;
; Context:	Process utility message
; Source:	Unrestricted
; Destination:	Any process
; Interception:	Not necessary, as the default handler provides the message's
;		utility.
; Pass:	cx:dx	- object class for the new thread
;			  If you don't have any special methods to handle in
;			  this thread, besides those intended for objects run
;			  by the thread, you can just specify ProcessClass as
;			  the object class.
; 		bp	- stack size for the new thread, or NULL for the
;			  default stack size (512 bytes)
; Return:	carry clear if thread created:
;		ax	- handle of new thread
;		cx, dx, bp - destroyed
;


;------------------------------------------------------------------------------
;		Internally used methods
;------------------------------------------------------------------------------

MSG_PROCESS_INSTANTIATE			message
;
; MSG_PROCESS_INSTANTIATE is used within the kernel to do instantiation via
; remote calls.  This method SHOULD NOT be subclassed.

MSG_PROCESS_EXIT			message
;
; MSG_PROCESS_EXIT is used internally to flush the process's event
; queue before exiting.
;
; Context:	Process/Thread death mechanism
; Source:	Internal (Default process handler for MSG_META_DETACH)
; Destination:	self
; Pass:		cx 	- exit code
;		dx:bp 	- OD to send MSG_META_ACK to after thread is completely
;			  dead
;		si	- data to pass as BP portion of "DX:BP = source of
;			  ACK" in MSG_META_ACK, as the source, this thread,
;			  requires only DX to reference.
; Return:	Doesn't.  Default handler is ThreadDestroy.


MSG_PROCESS_STARTUP_UI_THREAD		message
;
; Called by application process's to cause the UI thread, if one is
; needed, to be created, & resources marked as "ui-object" to be modified to
; be run by it.  This message is generally called as part of a process's
; MSG_ATTACH handler, to ensure that all ui-run objects have a 
; thread before any messages are attempted to be delivered to them.
; The thread will always receive a MSG_META_ATTACH as its first event.
;
; Context:	Part of attach/startup mechanism
; Source:	Generally a subclass of ProcessClass, at MSG_META_ATTACH. Is
;		called by GenProcessClass from within its handler of
;		MSG_META_ATTACH.
; Destination:	First thread of application process
; Interception:	Not generally intercepted.  MSG_PROCESS_CREATE_UI_THREAD, which
;		is called by the default handler of this message to perform
;		actual creation of thread if needed, is generally what is
;		intercepted to change default behavior.
; Pass:		nothing
; Return:	carry clear if thread created
;		ax, cx, dx, bp - destroyed


MSG_PROCESS_COPY_CHUNK_IN			message
; Copy a memory range into a local memory chunk in an object block
;
; Context:	Process utility message
; Source:	?
; Destination:	?
; Interception:	Not necessary, as default handler provides desired behavior
; Pass: 	dx		- # bytes on stack (size CopyChunkInFrame)
;		ss:bp 		- pointer to CopyChunkInFrame on stack
;
;	if Mode is CCM_OPTR, source is <cx=block><dx=chunk>
;		full chunk copied
;	if Mode is CCM_FPTR, source is <cx=segment><dx=offset>
;		size to copy passed in CCIF_copyFlags
;	if Mode is CCM_HPTR, source is <cx=block><dx=offset>
;		size to copy passed in CCIF_copyFlags
;	If Dirty flag set in CCIF_copyFlags, chunk handle is set DIRTY when
;	created.
;	If Dirty flag cleared in CCIF_copyFlags, chunk handle is set
;	IGNORE_DIRTY when created.
;
; Returns:	ax - chunk handle created
;		cx, dx, bp - destroyed
;

MSG_PROCESS_COPY_CHUNK_OVER			message
; Copy a memory range over a local memory chunk in an object block
;
; Context:	Process utility message
; Source:	?
; Destination:	?
; Interception:	Not necessary, as default handler provides desired behavior
; Pass: 	dx		- # bytes on stack (size CopyChunkOVerFrame)
;		ss:bp 		- pointer to CopyChunkOVerFrame on stack
;
;	if Mode is CCM_OPTR, source is <cx=block><dx=chunk>
;		full chunk copied
;	if Mode is CCM_FPTR, source is <cx=segment><dx=offset>
;		size to copy passed in CCOVF_copyFlags
;	if Mode is CCM_HPTR, source is <cx=block><dx=offset>
;		size to copy passed in CCOVF_copyFlags
;	If Dirty flag set in CCOVF_copyFlags, chunk handle is set DIRTY when
;	created.
;
; Returns: 	ax - chunk overwritten/created
;		cx - bytes copied
;		dx, bp - destroyed

MSG_PROCESS_COPY_CHUNK_OUT			message
;Copy a memory range from a local memory chunk in an object block
;
; Context:	Process utility message
; Source:	?
; Destination:	?
; Interception:	Not necessary, as default handler provides desired behavior
; Pass:		dx		- # bytes on stack (size CopyChunkOutFrame)
;		ss:bp		- pointer to CopyChunkOutFrame on stack
;
;	if Mode is CCM_OPTR, dest is <passed block><CREATED chunk>
;		full chunk copied
;	if Mode is CCM_FPTR, dest is <passed segment><passed offset>
;		size to copy passed in CCOF_copyFlags
;	if Mode is CCM_HPTR, dest is <CREATED BLOCK><0>
;		size to copy passed in CCOF_copyFlags
;	If using mode CCM_OPTR:
;		If DIRTY flag set in CCOF_copyFlags, then new chunk is set
;		DIRTY when created
;		If DIRTY flag clear in CCOF_copyFlags, then new chunk is set
;		IGNORE_DIRTY.
;	
; Returns: 	ax - created chunk/block handle
;		cx - # bytes copied
;		dx, bp - destroyed

MSG_PROCESS_FLUSH_PROCESS_QUEUE		message
;
; This do-nothing method can be used to flush the queue of a process
; by sending it via ObjMessage with the flag MF_CALL set.
;
; Context:	Process utility message
; Source:	?
; Destination:	?
; Interception:	No point. Is not intended to be handled.
; Pass:		nothing
; Returns:	nothing
;		ax, cx, dx, bp - presume to be destroyed


MSG_PROCESS_FINAL_BLOCK_FREE	message
;
; Part of the object block mechanism, this message is called on the process
; to actually free the memory block.  Is provided so that UI can intercept
; & perform additional error checking with regards to references to this block.
;
; Context:	Part of object block destruction mechanism
; Source:	Internal destruction mechanism only, which is started via
;		MSG_META_BLOCK_FREE or ObjFreeObjBlock
; Destination:	ProcessClass object of geode owning block
; Interception:	Is intercepted by UI only for EC purposes.  If intercepted,
;		superclass must be called (at which time the block is freed).
; Pass: 	cx - block handle
; Return:	nothing
;		ax, cx, dx, bp - destroyed

MSG_PROCESS_CALL_ROUTINE	message
;
; Call the given routine.  This is a low-level mechanism to allow interrupt
; code to use an existing thread.  Use with caution!
;
; Context:	None
; Source:	Anywhere
; Destination:	ProcessClass object
; Interception:	Never intercepted
; Pass: 	ss:bp - ProcessCallRoutineParams
; Return:	nothing
;		ax, cx, dx, bp - destroyed

ProcessCallRoutineParams	struct
    PCRP_address	vfptr
    PCRP_dataAX		word
    PCRP_dataBX		word
    PCRP_dataCX		word
    PCRP_dataDX		word
    PCRP_dataSI		word
    PCRP_dataDI		word
ProcessCallRoutineParams	ends

protominor KernelNewForZoomer

MSG_PROCESS_CREATE_EVENT_THREAD_WITH_OWNER		message
;
; This is a utility method that one can send to oneself to create a new
; event-driven thread. It cannot be used to create a non-event-driven
; thread (use ThreadCreate instead). This is implemented at ProcessClass
; and takes care of all the cruft of creating a new event-driven thread.
; The thread will always receive a MSG_META_ATTACH as its first event.
;
; Context:	Process utility message
; Source:	Unrestricted
; Destination:	Any process
; Interception:	Not necessary, as the default handler provides the message's
;		utility.
; Pass:	cx:dx	- object class for the new thread
;			  If you don't have any special methods to handle in
;			  this thread, besides those intended for objects run
;			  by the thread, you can just specify ProcessClass as
;			  the object class.
; 		bp	- stack size for the new thread, or NULL for the
;			  default stack size (512 bytes)
;		si - geode to own the thread
; Return:	carry clear if thread created:
;		ax	- handle of new thread
;		cx, dx, bp - destroyed

protominor DiscardObjBlock

MSG_PROCESS_OBJ_BLOCK_DISCARD			message
;
; This message causes the passed obj block to be discarded. 
; This message does not flush any queues or do any other in-use checking -
; the caller should have done this already.
;
; Context: 	Object death mechanism
; Source:	Unrestricted
; Interception: Not generally intercepted
; Pass: 	cx - block to discard
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

protominor InstantiateForThread

MSG_PROCESS_INSTANTIATE_FOR_THREAD		message
;
; MSG_PROCESS_INSTANTIATE_FOR_THREAD is used within the kernel to do
; instantiation via remote calls.  This method SHOULD NOT be subclassed.
;

protoreset

;------------------------------------------------------------------------------
;	Constants & Structures
;------------------------------------------------------------------------------

CopyChunkMode	etype byte
	CCM_OPTR	enum CopyChunkMode
	;from <object block><chunk>
	; (or to <object block><CREATED CHUNK)

	CCM_HPTR	enum CopyChunkMode
	;from <mem block><offset>
	; (or to <CREATED mem block>)

	CCM_FPTR	enum CopyChunkMode
	;from/to <seg><offset>

	CCM_STRING	enum CopyChunkMode	; TEMP

CopyChunkFlags	record
	CCF_DIRTY:1
	;DIRTY	- if set, any created chunk is set DIRTY
	;	  if clear, any created chunk is set IGNORE_DIRTY

	CCF_MODE CopyChunkMode:2

	CCF_SIZE:13
	; # bytes to copy (Not used for CCM_OPTR)

CopyChunkFlags	end
;
;Structure passed on stack to MSG_PROCESS_COPY_CHUNK_IN
;
CopyChunkInFrame	struct	
	CCIF_copyFlags	CopyChunkFlags
	CCIF_source	dword
	CCIF_destBlock	hptr
		; (must be an object block)
CopyChunkInFrame	ends

;
;Structure passed on stack to MSG_PROCESS_COPY_CHUNK_OVER
;
CopyChunkOVerFrame	struct
	CCOVF_copyFlags	CopyChunkFlags
	CCOVF_source	dword
	CCOVF_dest	optr
		; If dest chunk is 0, then creates new chunk	
CopyChunkOVerFrame	ends

;
;Structure passed on stack to MSG_PROCESS_COPY_CHUNK_OUT
;
CopyChunkOutFrame	struct	
	CCOF_copyFlags	CopyChunkFlags
	CCOF_source	optr
	CCOF_dest	dword
CopyChunkOutFrame	ends

ProcessClass	endc

EndKernel
