MetaClass: 2.1 Utility Messages: Object Creation and Destruction

These messages handle creation, destruction, and initialization of all objects. The function and use of many of these messages are given in .

MSG_META_INITIALIZE

void	MSG_META_INITIALIZE();

Every object class should provide a handler for this message which should call the superclass and then perform any initialization of the instance data required. This message is not delivered to statically declared objects because they are already initialized.

Note that GenClass and VisClass have a default handler that sets up the Gen and Vis parts automatically.

This message is not delivered to objects whose only master part is MetaClass itself.

Source: Object system itself, often in the middle of attempting to deliver another message to an object that hasn't yet been initialized.

Destination: Object whose instance data is not yet initialized.

Parameters: None.

Return: Nothing.

Interception: Any class wishing to have default instance data values other than all zeros should intercept this message to fill in the initial values for its instance data. For classes other than master classes, standard procedure is to call the superclass first, then perform any additional instance data initialization necessary. Master classes should not call the superclass, as MSG_META_INITIALIZE is unique among messages in that it is sent only to classes within the particular master group that needs to be initialized. Handlers of MSG_META_INITIALIZE should limit their activities to just stuffing instance data--specifically, object messaging is not allowed (though scanning vardata is OK). Object classes that inherit instance data (all but MetaClass ) should call MSG_META_INITIALIZE on their superclass to initialize that portion of their instance data. In addition, they must initialize their own portion of the instance data (start by assuming it's all zeros). The order won't matter, so long as the handler doesn't depend on the inherited instance data having any particular value. When in doubt, call the superclass first.

MSG_META_ATTACH

void 	MSG_META_ATTACH();

This message is used for two different purposes: It can be sent to any geode that has a process aspect when the geode is first loaded. It can also be sent in the object world to notify objects on an "active list" that the application has been brought back up from a state file. As the method is used for different purposes, the data passed varies based on usage. Because of this difference in parameters, normally C applications will use one of the aliases for this message (MSG_META_ATTACH_PROCESS ,MSG_META_ATTACH_THREAD , MSG_META_ATTACH_GENPROCESSCLASS , MSG_META_ATTACH_OBJECT, andMSG_META_ATTACH_GENAPPLICATION , each described below.)

MSG_META_ATTACH_PROCESS

@alias (MSG_META_ATTACH)
 void 	MSG_META_ATTACH_PROCESS(
        word 	value1,
        word 	value2);

This message is sent to any geode which has a process when the geode is first loaded. By default, the handler for this message does nothing.

Source: GeodeLoad() kernel routine.

Destination: Newly created Process object (but not GenProcess object).

Parameters: value1 Upper half of GeodeLoad() appInfo argument.

value2: Lower half of GeodeLoad() appInfo argument.

Return: Nothing.

Interception: No default handling provided, so if you are spawning an extra process and that process needs to do some initialization, then intercept this message.

MSG_META_ATTACH_GENPROCESSCLASS

@alias (MSG_META_ATTACH)
 void 	MSG_META_ATTACH_GENPROCESSCLASS(
        MemHandle appLaunchBlock);

This message is sent to the GenProcess object when the geode is first loaded. By default, the handler for this message calls MSG_PROCESS_STARTUP_UI_THREAD , which checks to see if there are any resources of the application which are marked as "ui-object" (they are marked this way in the .gp file), that is, to be run by a UI thread. If so, it then calls MSG_PROCESS_CREATE_UI_THREAD to create that thread, then marks the "ui-object" blocks as run by that thread.

The handler next calls one of the following messages:

MSG_GEN_PROCESS_OPEN_APPLICATION: For applications which are being started up regularly (that is, not restoring from a state file) and will appear on screen.
MSG_GEN_PROCESS_OPEN_ENGINE: For those applications that will operate in engine mode (i.e. non-visual).
MSG_GEN_PROCESS_RESTORE_FROM_STATE: For applications which are restoring from state. This is the case for applications that were running at the previous shutdown.

Source: GeodeLoad() kernel routine.

Destination: Newly created GenProcessClass (or subclass thereof) object.

Parameters: appLaunchBlock Block handle to block of structure AppLaunchBlock .

Return: Nothing.

Note that the passed AppLaunchBlock is destroyed.

Interception: No default handling provided, so if you are spawning an extra process and that process needs to do some initialization, then intercept this message.

MSG_META_ATTACH_GENAPPLICATION

@alias (MSG_META_ATTACH)
 void 	MSG_META_ATTACH_PROCESS(
        MemHandle 	bh1,
        MemHandle 	bh2);

This message is sent to the GenApplication object by GenProcessClass when the application starts up (either for the first time, or when being restored from a state file).

Source: GenProcess object.

Destination: GenApplication object.

Parameters: bh1 Block handle to block containing AppLaunchBlock parameters.

bh2: Extra state block from state file, or NULL if none. This is the same block as returned from MSG_GEN_PROCESS_CLOSE_APPLICATION in some previous detach operation.

Return: Nothing.

Note that the AppLaunchBlock is destroyed.

Interception: Not generally required, since the default handler broadcasts the message out to everything on the application's active lists. This act causes the interface for the application to come up on screen.

MSG_META_ATTACH_OBJECT

@alias (MSG_META_ATTACH)
 void 	MSG_META_ATTACH_OBJECT(
        word	 	flags,
        MemHandle 		appLaunchBlock,
        MemHandle 		extraState);

This message is sent to any object on the GenApplication object's active lists, or on one of those object's active lists. Note that this will not happen until the GenApplication is set usable by the GenProcess object.

Source: GenApplicationClass object.

Destination: Any object.

Parameters: flags Flags providing state information.

appLaunchBlock: Handle of AppLaunchBlock , or NULL if none.
extraState: Handle of extra state block, or NULL if none. This is the same block as returned from MSG_GEN_PROCESS_CLOSE_APPLICATION , in some previous detach.

Return: Nothing.

Interception: Standard UI objects defined as needing to be placed on an active list will intercept this message to do whatever it is that they needed to do when the application is first loaded. Objects intercepting this message should call the superclass, in case it expects to receive this notification itself.

Warnings: If the specific UI uses this mechanism, then the GenProcessClass will have already destroyed the AppLaunchBlock and extra state block by the time the MSG_META_ATTACH is sent to objects on its active list.

MSG_META_ATTACH_THREAD

@alias (MSG_META_ATTACH)
 void 	MSG_META_ATTACH_THREAD();

This message is sent to any thread spawned by MSG_PROCESS_CREATE_EVENT_THREAD .

Source: Kernel.

Destination: Newly created thread, specifically the class designated to handle the thread's messages (a subclass of ProcessClass ).

Parameters: None.

Return: Nothing.

Interception: No default handling provided, so if you are spawning an extra process and that process needs to do some initialization, then intercept this message.

MSG_META_APP_STARTUP

void	MSG_META_APP_STARTUP(
        MemHandle		appLaunchBlock);

This message is related to MSG_META_ATTACH; the message is sent by the generic UI to the GenApplication object before it sends MSG_META_ATTACH to it. MSG_META_ATTACH is only sent when the application is becoming available to the user; if an application should be opened as a server without presenting any UI to the user, MSG_META_APP_STARTUP will be the only message sent to the application object upon start-up.

The default handler for this message will pass it on to all members of the MGCNLT_APP_STARTUP list.

Source: GenProcessClass ; forwarded by GenApplicationClass to other objects. This message is sent upon application start-up before the UI for an application has been attached.

Destination: Any object that needs to be notified when the application is launched, regardless of whether the user will be interacting with the application.

Parameters: appLaunchBlock Handle of an AppLaunchBlock .

Return: The AppLaunchBlock is preserved.

Interception: Usually intercepted by any object on the MGCNLT_APP_STARTUP list.

MSG_META_UPDATE_WINDOW

void	MSG_META_UPDATE_WINDOW(
        UpdateWindowFlags		updateFlags,
        VisUpdateMode		updateMode);

This message is sent as part of the system's window update mechanism. Typically, this message is sent to windowed objects on the GAGNLT_WINDOWS list when the GenApplication object becomes GS_USABLE.

The message passes a bitfield of UpdateWindowFlags . These flags determine the type of action prompting the window update.

UWF_ATTACHING: If set, the message is being sent because the application is attaching.
UWF_DETACHING: If set, the message is being sent because the application is detaching.
UWF_RESTORING_FROM_STATE: If set, the application is restoring from state. This flag will only be set if UWF_ATTACHING is also set.
UWF_FROM_WINDOWS_LIST: If set, the message is being sent because the object is on the GAGCNLT_WINDOWS list, and not because it was later built on demand. This flag will only be set if UWF_ATTACHING is also set.

Source: Window update mechanism.

Destination: Entries on the Application's GAGCNLT_WINDOWS list.

Parameters: updateFlags UpdateWindowFlags .

updateMode: VisUpdateMode .

Interception: Generally not intercepted.

MSG_META_DETACH

void	MSG_META_DETACH(
        word	callerID,
        optr	caller);

This message severs the links between an object and the rest of the system. The exact way this is handled depends on the object being detached. For full information on detaching objects, see the GEOS Programming chapter.

The "state" of the object is left intact, in case an image of the object needs to be saved away in a state file for later re-creation. MSG_META_DETACH sent to an application's process will start the process by which it is detached from the system, and then exited. MSG_META_DETACH is asynchronous, in that it need not complete its job immediately upon being called. Rather, it may take as much time, invoking and waiting for the completion of subsidiary detaches (say of child objects needing to perform special actions to detach, or of threads created earlier), before it responds with MSG_META_ACK to let its caller know that the detach has completed.

Source: Kernel, other objects relaying detach message.

Destination: GenProcess, GenApplication, objects on active lists.

Parameters: callerID A number of your choosing. This number will be passed back to caller in MSG_META_ACK in the callID parameter.

caller: Object which should be sent a MSG_META_ACK when detaching object has finished.

Return: Nothing.

Interception: Intercepted as a means of finding out that the application is shutting down. Call the superclass in case it needs such notification.
If you create additional threads, or object classes which need to be notified when the application is about to be exited, you may need to extend the detach mechanism by intercepting MSG_META_DETACH in a subclass of an object already receiving that message, such as GenApplication, GenControl, GenInteraction dialogs, etc. You must make sure that all objects you've sent MSG_META_DETACH to have responded with a MSG_META_ACK before your object can reply with MSG_META_ACK . Remember that your superclass may be sending MSG_META_DETACH . The kernel provides some default behavior in MetaClass , and some utility routines, to make this a simpler task. The default handler for MSG_META_DETACH , for instance, at a leaf object (one which doesn't propagate the MSG_META_DETACH ), performs the required response (sending a MSG_META_ACK ). Thus, leaf objects can just intercept MSG_META_DETACH for notification purposes, then call the superclass, and worry no more. The utility routinesObjInitDetach() and ObjEnableDetach() work in conjunction with a default MSG_META_ACK handler in MetaClass to keep track of how many outstanding acknowledgments are being waited for, and call MSG_META_DETACH_COMPLETE on your object once all acknowledgments have returned (the count reaches zero). The default handler for MSG_META_DETACH_COMPLETE then generates the acknowledgment response required of your object to complete its detach. You may optionally call the superclass before sending the detach message to your children and dependents, depending on which order you want things to detach in. The call to the superclass must happen between the ObjInitDetach() and ObjEnableDetach() , however.

MSG_META_DETACH_COMPLETE

void	MSG_META_DETACH_COMPLETE();

This message is sent to an object being detached when all of its children and active participants have acknowledged the detach. For full information on detaching objects, see the GEOS Programming chapter.

MSG_META_DETACH_COMPLETE is sent to the object which called ObjInitDetach() . This will happen when as many acknowledgments have been received as ObjIncDetach() was called, and ObjEnableDetach() was called. The MetaClass handler for this message sends MSG_META_ACK to the OD passed to the ObjInitDetach() call. This message is provided so that an object will know when all of its children have detached. Note that this message is received only if ObjInitDetach() has been called for this object. Note also that your superclass may call ObjInitDetach() without your knowing.

Source: MetaClass handler for MSG_META_ACK , if detach count has dropped to zero (i.e. no outstanding requests), for objects that are detach nodes only (make use of ObjInitDetach() or ObjEnableDetach() ).

Destination: Self.

Parameters: None.

Return: Nothing.

Interception: This is a handy message to intercept when using the ObjInitDetach() mechanism and need to know when all objects asked to detach have responded. Calling the superclass at this point in time will cause an MSG_META_ACK to go back to whatever object sent the MSG_META_DETACH to this object originally. There is no requirement to call the superclass at this time, and in fact this is a way to prolong the detach cycle for this object-- by simply starting up another ObjInitDetach() sequence, for instance.

MSG_META_DETACH_ABORT

void	MSG_META_DETACH_ABORT();

This message causes a detach to be aborted. This can cause some very complex synchronization problems and should not be used lightly. You will find very little call to use it.

Source: Renegade object on active list, after having received MSG_META_DETACH , as an alternative to replying with MSG_META_ACK .

Destination: The optr passed in MSG_META_DETACH .

Interception: Handled by GenField to deal with applications that refuse to die, and GenSystem for Fields that have problem applications. Other than that, any detach node wishing to provide this service will have to figure out a way to do it itself.

Parameters: None.

Return: Nothing.

MSG_META_APP_SHUTDOWN

void	MSG_META_APP_SHUTDOWN(
        word		callerID,
        optr		ackOD);

This message is the complement to MSG_META_APP_STARTUP. This message is sent to objects on the MGCNLT_APP_STARTUP list before an application exits but after the UI for the application is detached. Essentially, it operates in the same manner as MSG_META_DETACH except that the receiving object sends MSG_META_SHUTDOWN_ACK when its shutdown is complete.

Source: Sent by GenProcessClass after detaching the UI but before exiting the application; if the UI was never attached (i.e. it handled MSG_META_APP_STARTUP but not MSG_META_ATTACH) the UI will obviously not be detached.

Destination: Any object that needs to be notified when the application is about to exit.

Parameters: callerID Word of data for caller's use.

ackOD: Optr of object to be sent MSG_META_SHUTDOWN_ACK.

Interception: Usually intercepted by objects on the MGCNLT_APP_STARTUP list.

MSG_META_SHUTDOWN_COMPLETE

void	MSG_META_SHUTDOWN_COMPLETE();

This message is sent to the object that initiated the detach sequence after it has received MSG_META_SHUTDOWN_ACK for each ObjIncDetach() that was previously called. This message is only sent if ObjInitDetach() was previously called passing the message MSG_META_APP_SHUTDOWN.

The default handler for this message sends MSG_META_SHUTDOWN_ACK to the object passed in the original ObjInitDetach() call.

Source: MetaClass handler for MSG_META_SHUTDOWN_ACK if detach count reaches zero (i.e. no outstanding requests), for objects that are shutdown nodes only (i.e. make use of ObjInitDetach() .)

Destination: The object sends this message to itself.

Interception: Intercept if you are using theObjInitDetach() mechanism and need to be notified when all objects have been notified of the detach.

MSG_META_SHUTDOWN_ACK

void	MSG_META_SHUTDOWN_ACK(
        word		callerID,
        optr		ackOD);

This message is sent back in response to a MSG_META_APP_SHUTDOWN. This message serves to notify the object the object has fulfilled the request.

Source: Object having received MSG_META_APP_SHUTDOWN. The default handler will dispatch MSG_META_SHUTDOWN_ACK after MetaClass has processed MSG_META_APP_SHUTDOWN. (You could, of course, intercept MSG_META_APP_SHUTDOWN and send MSG_META_SHUTDOWN_ACK yourself in your handler.)

Destination: Optr passed in MSG_META_APP_SHUTDOWN.

Parameters: callerID Data passed in MSG_META_APP_SHUTDOWN.

ackOD: Object which has completed shutting down.

Interception: MetaClass provides default handling for this message when using the ObjInitDetach() mechanism. Objects not using this mechanism will want to intercept this message if there is a need to know when the object has completed shutting down.

MSG_META_ACK

void	MSG_META_ACK(
        word	callerID,
        optr	caller);

This message acknowledges a detach message. It is sent by objects that have been notified of another object's detach. The default handler for MSG_META_DETACH simply sends MSG_META_ACK back to the object that sent the detach message.

Source: Object having received MSG_META_DETACH (default handler in MetaClass will reflexively respond to any MSG_META_DETACH with a MSG_META_ACK , though you can change this behavior either by using ObjInitDetach() or by not letting the message get to the MetaClass handler, and responding yourself with a MSG_META_ACK sometime later).

Destination: The optr passed in MSG_META_DETACH.

Interception: MetaClass provides default handling of this message, for objects using the ObjInitDetach() mechanism. Objects not using this mechanism will want to intercept this if there is a need to know when the object asked to detach earlier has completed its detach.
MSG_META_ACK is normally inherited from MetaClass which calls ObjEnableDetach() . This routine decrements the detach count, and when that count reaches zero, sends a MSG_META_DETACH_COMPLETE to the object itself.

Warnings: If you are expecting a MSG_META_ACK back from anything, make sure you are using the mechanism initiated with ObjInitDetach() yourself, or you should handle MSG_META_ACK to prevent MetaClass from assuming you are using such a mechanism.

Parameters: callerID data passed to MSG_META_ACK

caller: object which has completed detaching

Return: Nothing.

MSG_META_BLOCK_FREE

void	MSG_META_BLOCK_FREE();

This message initiates a sequence which will free an entire object block when received by any object within that block. The block will be freed when its in-use count reaches zero and the message queues for the block have been cleared.

This is a fairly low-level operation, and should be performed only after the objects in the block have been removed from any tree(s) they are attached to, and are otherwise "shut down." For generic objects, this generally means first calling MSG_GEN_SET_NOT_USABLE , then MSG_GEN_REMOVE_CHILD before using this message. For Visible objects, MSG_VIS_REMOVE will both visually shut down the visible tree, and then remove it from its parent.

Source: Unrestricted.

Destination: Any object within a block that is ready to have a low-level delete performed on it (i.e. isn't on screen, isn't linked to objects in other blocks, etc.).

Interception: Unnecessary, as MetaClass does the right thing.

Parameters: None.

Return: Nothing.

MSG_META_OBJ_FREE

void	MSG_META_OBJ_FREE();

This message initiates a sequence which will free an object. The object will be freed after its message queues have been flushed.

This is a fairly low-level operation, and should be performed only after the object has been removed from any tree it is attached to and is otherwise "shut down." Consider using MSG_GEN_DESTROY for generic objects, MSG_VIS_DESTROY for visible ones.

Source: Unrestricted.

Destination: Any object within a block that is ready to have a low-level delete performed on it (i.e. isn't on screen, isn't linked to objects in other blocks, etc.).

Interception: Unnecessary, as MetaClass does the right thing.

Parameters: None.

Return: Nothing.

MSG_META_DEC_BLOCK_REF_COUNT

void	MSG_META_DEC_BLOCK_REF_COUNT(
        MemHandle		block1,
        MemHandle		block2);

This message is a utility message to call MemDecRefCount() on one or two memory handles.

This message is useful for IACP, which initializes the reference count to the number of servers returned by IACPConnect() and records this message as the message to be returned. After each server has processed its information, the reference count will return to zero and the handles will be freed.

Source: Unrestricted.

Destination: Any object.

Parameters: block1 Handle of a block whose reference count should be decremented, or 0 if none.

block2: Handle of a block whose reference count should be decremented, or 0 if none.

Interception: Generally not intercepted.

MSG_META_OBJ_FLUSH_INPUT_QUEUE

void	MSG_META_OBJ_FLUSH_INPUT_QUEUE(
        EventHandle event,
        ObjFlushInputQueueNextStop nextStop,
        MemHandle 	objBlock);

This message clears out the message queues associated with an object. This is rarely, if ever called from within an application, and there is little call to subclass it.

This queue-flushing mechanism is used in the Window, Object, and Object Block death mechanisms. Objects that implement their own "hold up input" queues must redirect this message through that queue, so that it is flushed as well.

Source: Kernel (WinClose() ,WinSetInfo() , ObjFreeObjBlock() , MSG_META_OBJ_FREE , or MSG_META_BLOCK_FREE).

Destination: Should first be sent to the Kernel's Input Manager (See the routine ImInfoInputProcess() ). The message is then relayed first to the System Input Object (usually the GenSystemClass object), then to the Geode Input Object (usually a GenApplicationClass object), and finally to the owning process, which dispatches the passed event.

Parameters: event Event to dispatch upon conclusion of flush.

objBlock: Block Handle that flushing is being performed for (generally the handle of the destination object in the above event). This is the block from which the "OWNING GEODE", as referenced in the ObjFlushInputQueueNextStop enumerated type, is determined.
nextStop: ObjFlushInputQueueNextStop (Zero should be passed in call to first object, from there is sequenced by default MetaClass handler)

Return: Nothing.

Structures:

  typedef enum {
	OFIQNS_SYSTEM_INPUT_OBJ,
	OFIQNS_INPUT_OBJ_OF_OWNING_GEODE,
	OFIQNS_PROCESS_OF_OWNING_GEODE,
	OFIQNS_DISPATCH
} ObjFlushInputQueueNextStop;

Interception: Default MetaClass handler implements relay of message from one object to the next, and dispatches the passed event. Must be intercepted by any input-flow controlling objects (System object, VisContent) which implement "hold-up" queues that hold up input-related messages. The handlers in such cases should pipe this method through the hold-up queue as it does with the other messages, and finish up when it comes out by sending this message, with all data intact, to the superclass for continued default processing.

GEOS SDK TechDocs |

2 Utility Messages | Next:

2.2 Class Messages