Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 2 - Event Manager / Using the Event Manager

Creating a Size Resource

Your application should include a size ('SIZE') resource. You use a 'SIZE' resource to inform the Operating System about the memory size requirements for your application so that the Operating System can set up a partition of the appropriate size for your application. You also use the 'SIZE' resource to indicate certain scheduling options to
the Operating System, such as whether your application can accept suspend and
resume events.

You can also specify additional information in the 'SIZE' resource in System 7, indicating whether your application is 32-bit clean, whether your application supports stationery documents, whether your application uses TextEdit's inline input services, whether your application wishes to receive notification of the termination of any applica- tions it has launched, and whether your application wishes to receive high-level events.

A 'SIZE' resource consists of a 16-bit flags field, followed by two 32-bit size fields. The flags field specifies operating characteristics of your application, and the size fields indicate the minimum and preferred partition sizes for your application. The minimum partition size is the actual limit below which your application will not run. The preferred partition size is the memory size at which your application can run most effectively and that the Operating System attempts to secure upon launch of your application. If that amount of memory is unavailable, your application is placed into
the largest contiguous block available, provided that it is larger than the specified minimum size.

Note

If the amount of available memory is between the minimum and the
preferred sizes, the Finder displays a dialog box asking if the user wants to run the application using the amount of memory available. If your
application does not have a 'SIZE' resource, it is assigned a default
partition size of 512 KB and the Process Manager uses a default value
of FALSE for all specifications normally defined by constants in the
flags field. u

When you define a 'SIZE' resource, you should give it a resource ID of -1. A user can modify the preferred size in the Finder's information window for your application. If the user does alter the partition size, the Operating System creates a new 'SIZE' resource having a resource ID of 0. At application launch time, the Process Manager looks for a 'SIZE' resource with ID 0; if this resource is not found, it uses your original 'SIZE' resource with ID -1. This new 'SIZE' resource is also created when the user modifies any of the other settings in the resource.

When creating a 'SIZE' resource, you first need to determine the various operating characteristics of your application. For example, if your application has nothing useful to do when it is in the background, then you should not set the canBackground flag. Similarly, if you have not tested your application in an environment that uses all 32 bits of a handle or pointer for memory addresses, then you should not set the is32BitCompatible flag.

Listing 2-4 shows the Rez input for a sample 'SIZE' resource. (Rez is a resource compiler available with the MPW environment.)

Listing 2-4 The Rez input for a sample 'SIZE' resource

resource 'SIZE' (-1) {
   reserved,                     /*reserved*/
   acceptSuspendResumeEvents,    /*accepts suspend&resume events*/
   reserved,                     /*reserved*/
   canBackground,                /*can use background null */
                                 /* events*/
   doesActivateOnFGSwitch,       /*activates own windows in */
                                 /* response to OS events*/
   backgroundAndForeground,      /*application has a user */
                                 /* interface*/
   dontGetFrontClicks,           /*don't return mouse events */
                                 /* in front window on resume*/
   ignoreAppDiedEvents,          /*doesn't want app-died events*/
   is32BitCompatible,            /*works with 24- or 32-bit addr*/
   isHighLevelEventAware,        /*supports high-level events*/
   localAndRemoteHLEvents,       /*also remote high-level events*/
   isStationeryAware,            /*can use stationery documents*/
   dontUseTextEditServices,      /*can't use inline input */
                                 /* services*/
   reserved,                     /*reserved*/
   reserved,                     /*reserved*/
   reserved,                     /*reserved*/
   kPrefSize * 1024,             /*preferred memory size*/
   kMinSize * 1024               /*minimum memory size*/
};

The 'SIZE' resource specification in Listing 2-4 indicates, among other things, that the application accepts suspend and resume events, does processing in the background using null events, activates or deactivates any windows as necessary in response to operating-system events, can execute in both the foreground and background, and doesn't want to receive any mouse event associated with a resume event that was caused by the user clicking in the application's front window. It also indicates that the application doesn't want to receive Application Died events, can work in 24-bit or 32-bit addressing mode, does accept high-level events, including both local and network high-level events, does handle stationery documents, and doesn't use TextEdit's inline input services. In this example, the Rez-input file must define values for the constants kPrefSize and kMinSize; for example, if kPrefSize is set to 50, the preferred partition size is 50 KB.

The numbers you specify as your application's preferred and minimum memory sizes depend on the particular memory requirements of your application. Your application's memory requirements depend on the size of your application's static heap, dynamic heap, A5 world, and stack. (See "Introduction to Memory Management" in Inside Macintosh: Memory for complete details about these areas of your application's partition.)

The static heap size includes objects that are always present during the execution of your application--for example, code segments, Toolbox data structures for window records, and so on.

Dynamic heap requirements come from various objects created on a per-document basis (which may vary in size proportionally with the document itself) and objects that are required for specific commands or functions.

The size of the A5 world depends on the amount of global data and the number of intersegment jumps your application contains.

The stack contains variables, return addresses, and temporary information. The size of the application stack varies among computers, so you should base your values for the stack size according to the stack size required on a Macintosh Plus computer (8 KB).
The Process Manager automatically adjusts your requested amount of memory to compensate for the different stack sizes on different machines. For example, if you request 512 KB, more stack space (approximately 16 KB) will be allocated on machines with larger default stack sizes.

Unfortunately, it is difficult to forecast all of these conditions with any great degree of reliability. You should be able to determine reasonably accurate estimates for the stack size, static heap size, A5 world, and jump table. In addition, you can use tools such as MacsBug's heap-exploring commands to help you empirically determine your application's dynamic memory requirements.

See "The Size Resource" beginning on page 2-115 for additional information on the meaning of each of the fields and flags of a 'SIZE' resource.