TweetFollow Us on Twitter

March 97 - The OpenDoc Road

THE OPENDOC ROAD

Making the Most of Memory in OpenDoc

Troy Gaul and Vincent Lo

In Issue 28, we discussed how the OpenDoc Memory Manager works and how part editors manage Toolbox memory. This time we'll examine ways to use memory more efficiently in the OpenDoc environment.

We'll begin by talking about how to avoid memory leaks. Memory leaks, which can be a problem when developing traditional Macintosh applications, are as much a concern in OpenDoc. But because OpenDoc uses reference counting, there are a few extra things to pay attention to. We'll also discuss how to handle parameters correctly to avoid memory leaks, and we'll take a look at ways you can set up your part editor to maximize memory usage.

AVOIDING MEMORY LEAKS

OpenDoc objects and part editors use a reference-counting scheme that enables OpenDoc to keep track of which objects are in use. Each time a client acquires an object (through the object's Acquire method), the object's reference count is incremented by 1. When the object is no longer being used, the client releases it (by calling the object's Release method) and its reference count is decremented. The object's reference count indicates how many references to the object are being held by clients. When the reference count goes down to 0, the object can be destroyed without affecting any other objects. For more information on how reference counting works in OpenDoc, see the OpenDoc Road column in develop Issue 27, "Facilitating Part Editor Unloading."

If the acquired object doesn't get released when it should, the reference count doesn't go to 0 and the object remains in memory until the session ends. As a result, a memory leak occurs because the occupied memory can't be used during the session.

To avoid reference count errors, it helps to keep in mind which classes are reference-counted and which methods affect an object's reference count. OpenDoc uses reference counting on classes whose objects often have more than one client. These classes are subclasses of ODRefCntObject, and many are classes that part editors interact with directly.

In general, if a method name starts with "Acquire," the reference count of the object named in the method is incremented when the method is called. When the object is no longer needed, the caller should release it. For example, if a part editor calls ODDraft::AcquireFrame to access a frame object, the reference count of the returned frame object is incremented. After the editor is done using the frame reference, a call to the object's Release method (ODFrame::Release) must be made to avoid a memory leak.

Some methods return a reference-counted object without affecting the object's reference count. These methods usually start with "Get." For example, ODFacet::GetFrame returns the frame object with which the facet is associated without incrementing the reference count of the frame object. In this case, the caller shouldn't call ODFrame::Release. Typically, a Get method is used to return an invariant or unchanged attribute of an object. In the case of ODFacet, the facet acquires and stores a reference to its ODFrame object. This reference isn't released until the ODFacet object is deleted. When ODFacet::GetFrame is called, ODFacet returns the stored reference to the caller. Since this reference remains valid until the ODFacet is deleted, you can use it as long as the ODFacet is a valid object. If you want to use the returned ODFrame object beyond the ODFacet's lifetime, you should call Acquire on the ODFrame to ensure that you have a valid reference to it.

The best way to avoid reference count errors is to familiarize yourself with the OpenDoc API and understand how it affects an object's reference count. The OpenDoc Class Reference provides a detailed description of reference counting for each method.

Temporary objects to the rescue. The code for acquiring a reference-counted object for a brief period of time and then releasing it turns out to be quite complicated. Listing 1 shows how complicated it can be to handle a reference-counted object when using exception-handling code.


Listing 1. Handling reference-counted objects

ODFrame* frame = kODNULL;
ODVolatile(frame);
// Make sure that the frame can be used in
// the CATCH block.
SOM_TRY
   // Acquire the frame.
   frame = draft->AcquireFrame(ev, id);
   // Do something with the frame here.
   ...
   // Release it when done.
   frame->Release(ev);
SOM_CATCH_ALL
   if (frame)
      frame->Release(ev);
SOM_ENDTRY

To help alleviate this problem, OpenDoc provides a utility library that uses stack-based C++ objects to wrap references to OpenDoc reference-counted objects. These C++ objects are called temporary objects. Whenever such a C++ object goes out of scope, its destructor is called and releases the reference-counted object.

The code fragment shown in Listing 2 does the same thing as the example in Listing 1 but uses temporary objects instead. This code is simpler and less error-prone.


Listing 2. Easier handling of reference-counted objects

SOM_TRY
   TempODFrame frame =
         draft->AcquireFrame(ev, id);
   // Do something with the frame here.
   ...
SOM_CATCH_ALL
SOM_ENDTRY

The OpenDoc utility library provides temporary objects for 17 reference-counted classes, including ODPart, ODFrame, ODExtension, and ODStorageUnit. For more information on creating temporary objects, see the "Temporary Objects" section of Appendix A in the OpenDoc Cookbook.

The OpenDoc utility library also provides temporary objects for objects that aren't reference-counted, such as ODByteArray and ODIText. These OpenDoc types deserve special attention in regard to memory usage.

The ODByteArray structure contains three fields: _buffer, _maximum, and _length. The _buffer field points to a memory block whose size is indicated by the _maximum field. _length is the number of bytes used; it has to be less than or equal to the value of _maximum.

Generally, ODByteArray is used instead of a raw pointer because the size of the memory block is included. This enables SOM and OpenDoc to pass data between processes without relying on shared memory. But because the _buffer field is hidden in the ODByteArray, the memory block can easily be forgotten. Failing to free this memory block when an ODByteArray is deallocated creates a memory leak.

The ODIText structure stores a user-visible string. One of its fields contains the string's format; the other is an ODByteArray that contains the text string. The memory block in the ODByteArray needs to be freed when the ODIText structure is deallocated.

Handling in and out parameters. Memory leaks can also occur when parameters aren't handled correctly. In an OpenDoc method, each parameter is designated as in, out, or inout.

  • An in parameter passes data from the caller to the callee.
  • An out parameter transfers data from the callee to the caller. A method's result also acts as an out parameter.
  • An inout parameter passes data from the caller to the callee, which can then modify it and pass it back.
To determine a particular parameter's designation, you can check the ".idl" files, or see the OpenDoc Class Reference for detailed information on each parameter.

The parameter's designation defines the memory responsibility of the caller and callee. The part editor can use memory on the stack for parameters of primitive types or fixed-size data structures. But for strings, byte array buffers, and objects, the part editor must use the OpenDoc Memory Manager to do the following:

  • allocate and deallocate memory for in and inout parameters passed to an OpenDoc object
  • deallocate memory for out parameters returned from an OpenDoc object
  • allocate memory for out parameters returned from the part editor's methods
If a part editor calls an OpenDoc method and doesn't deallocate the out parameter, the memory won't be freed until the session ends, causing a memory leak.

Since it's impossible to know how a piece of memory is allocated, OpenDoc and part editors have to use the OpenDoc Memory Manager as the common memory management facility. This is the only way to ensure that memory allocated by OpenDoc can be freed by the part editor and vice versa.

SETTING UP YOUR PART EDITOR

Because your part editor is used in documents with other part editors as users construct compound documents, it's important to make the best use of memory. Let's talk about some of the things you can do to minimize memory usage.

Keep the data section small. When creating a part (which is a shared library), the linker will generate code and data sections. The code section contains the instructions that make up your part editor. This section is read-only because it's file-mapped onto read-only memory when virtual memory is in use. The data section is stored separately because it needs to be writeable; it contains globals, static variables, transition vectors, virtual tables, and so on.

A single in-memory or memory-mapped copy of the code section is shared by all processes in which that code is used. The data section is handled differently: Each process instantiates a copy of the data section, making globals per-process rather than per-computer or per-part. Also, because there is normally one process per OpenDoc document, a separate data section usually exists for each document that contains a part bound to your editor. Therefore, you should control the size of your data section so that copies of it don't take up too much memory when multiple documents are open.

Here's what you can do to keep the size of your data section down:

  • Limit your use of global variables -- Since globals are stored in the data section, use them only for those things that must be per-process globals.
  • Use read-only string constants -- String constants that are writeable must be located in your data section because the compiler assumes that you might write into the memory associated with them. If you have the compiler make your string constants read-only (by checking the Make Strings ReadOnly box in the PPC Processor panel in CodeWarrior, for example), these strings can be put into the code section instead of the data section. But remember that after doing this, you should not write to these string constants. You can still allocate memory in the OpenDoc heap for strings and write to them. You can also put string buffers, such as Str255 strings, on the stack in your code and write to them there. Note that any user-visible string constants should be stored in resources so that your editor can be localized.
  • Avoid virtual functions -- Space is made for virtual functions of C++ classes in the data section because the virtual tables must be written once (for each process) to point to the functions residing in the read-only code section. You can make the virtual table smaller by not making functions virtual. It's best to design your classes with as few virtual functions as possible, adding more only as the need arises.
  • Reduce the number of transition vectors -- For each import and export symbol in a library, there's a TVector, or transition vector. (CFM-68K calls them XVectors.) The TVector must be writeable because, like a virtual table, it has to be written once to point to the corresponding memory address when the code is loaded.

Reduce exports. By minimizing the number of symbols that are exported, you can save memory. Symbol name strings are stored in the PEF (Preferred Executable Format) container of your code fragment. If you're using a shared library that contains a framework or set of C++ classes, you usually need to export the symbols for each of the member functions in the shared library and import the relevant ones into your part editor to call them or subclass them. C++ functions have long symbol names because they include type signature information. As a result, the size of your code fragment can increase significantly.

This is particularly noticeable if you have multiple part editors that reference the same code, since they'll all have large tables of symbol names. You can use a tool like DumpPEF to check what type of information your code fragment contains and how much space it's taking up.

A workaround is to statically link classes to your part editor. This means fewer imports and less memory used. Of course, if you do this, you lose some of the advantages of sharing code via a shared library.

Package multiple part editors intelligently. If you're writing a suite of part editors for end users, it's a good idea to package them as separate editor files in the Editors folder. However, as mentioned earlier, if you want to share common code, the amount of memory that's used by all the editors combined can be substantial.

Packaging all your part editors and the common code in a single code fragment reduces the number of imports and exports to almost nothing. But then you can't update just one of the editors in your suite -- you have to replace the entire shared library. It's also detrimental if only one or two of your editors are being used, because the system loads the entire code fragment but only a portion of it is being referenced. This isn't as much of a problem if the user has virtual memory enabled, but without it, memory is wasted.

To combine multiple OpenDoc part editors into one code fragment, you have to compile the code for all of them together. You can do this either by putting them all into one project or by having multiple projects generate static library files and a master project that includes each of the single-part libraries. Then you need to make sure that the ClassData symbols for all the parts are exported as separate symbols, by using pragmas or a ".exp" file. Finally, you must include the 'nmap' resources from all the individual editors in the combined file. Of course, the IDs of these resources can't conflict, but since OpenDoc doesn't require any specific resource IDs for 'nmap' resources, that shouldn't be a problem to set up.

Use SOM classes instead of C++. If you'd like to separate framework code from part editor code (for example, to have multiple editors share the same framework or set of classes), note that there are several advantages to using SOM classes instead of C++ classes.

With SOM on the Mac OS, you only have to export the class's ClassData symbol. The virtual tables are maintained by the SOM kernel; they don't exist in your data section.

Since SOM has so little overhead, you can package multiple editors as separate code fragments (either in separate, replaceable files or in a single file). Editors that aren't being used won't be loaded.

You can also reduce the granularity of your shared libraries, such that different classes are in different shared libraries (again, in separate files or the same file). This allows you to split up your framework so that only the sections that the client needs are loaded into memory. For example, if you have one part editor that embeds other editors and another that doesn't, but they share the same framework, the framework's embedding code can be in a separate shared library from the code that's needed by all part editors.

SOM supports release-to-release binary compatibility, and it deals with the fragile base class problem of C++. It also defines a binary interface that supports languages other than C++. Currently, emitters on the Mac OS for C and C++ are available. Other languages can also be supported.

Don't be afraid to use SOM. Better tools for building SOM classes are being released. In particular, Direct-to-SOM support has been added to Metrowerks CodeWarrior's C++ compiler and Apple's MrCpp, so you can build SOM classes with much less effort and with a more familiar syntax.

Use #pragma internal. Space is also wasted when it's set aside for instructions and never used. By default, functions on a PowerPC(TM) processor are assumed to be external, so for the processor to jump to the routine, it's expected to go through a TVector. To do this, the compiler leaves room in the code for the linker to add the necessary instruction to restore the TOC (Table Of Contents) after a jump to a TVector. If it turns out that the routine is in the same code fragment, restoring the TOC isn't necessary, but because the space has already been inserted, the linker has little recourse but to put a no-op instruction in that place. (The code was generated expecting certain offsets, so the linker can't shuffle the code around easily.) Space is then wasted for calls that are internal to the code fragment.

There are a couple of ways around this. One thing you can do is to declare a function with the keyword static (this means that it can't be used outside the file it's defined in) so that the compiler can tell it's an internal function. You can also use the internal pragma in CodeWarrior. The following code marks the declaration of two functions as internal by enclosing them in a #pragma internal block. This informs the compiler that calls to those functions can be assumed to be internal calls, and it won't leave space for restoring the TOC after a TVector call.

#pragma internal on
   void InternalFunction();
   ODBoolean AnotherInternalFunction(short count);
#pragma internal reset
Note that a function internal to your code can still be an export from your shared library. In this case, your header should conditionalize its inclusion of #pragma internal for your own use so that external clients don't mistakenly see it as internal.
    This technique is not used for CFM-68K code because calls there are assumed to be internal unless they're marked otherwise (with #pragma import).*
The MrPlus profiling tool can also be used to get rid of unneeded no-op instructions. You can get this tool and its documentation on the E.T.O. and MPW Pro CDs.

EVERY BYTE COUNTS

OpenDoc presents a new model for constructing software. However, many of the techniques you've used for the traditional application model can still be applied to the OpenDoc environment. By also incorporating some of the suggestions we've brought up here, you'll be able to further reduce your part editor's footprint and avoid memory leaks.


    RELATED READING

    This documentation is available on the OpenDoc Developer Release CD and on the OpenDoc Web site (http://www.opendoc.apple.com).

    • OpenDoc Programmer's Guide for the Mac OS by Apple Computer, Inc. (Addison-Wesley, 1995). The OpenDoc Class Reference for the Mac OS is provided on a CD that accompanies this book.
    • OpenDoc Cookbook for the Mac OS by Apple Computer, Inc. (Addison-Wesley, 1995).


TROY GAUL (tgaul@apple.com) recently joined the OpenDoc engineering team, where he's working with JavaTM. Having also written the sample part editor formerly known as Cappuccino, he has a caffeine buzz that should last into the next century.*

VINCENT LO (vincent@apple.com) is Apple's technical lead for OpenDoc. Since he recently introduced the OpenDoc team to Hong Kong cinema, it occasionally happens that the OpenDoc engineering meeting resembles a scene from a Hong Kong action movie.*


Thanks to Jens Alfke, David Bice, and Steve Smith for reviewing this column.*

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Adobe Illustrator 24.0.3 - Professional...
You can download Adobe Illustrator for Mac as a part of Creative Cloud for only $20.99/month (or $9.99/month if you have also purchased an earlier software version). Adobe Illustrator for Mac is the... Read more
Adobe Dreamweaver CC 2020 20.1 - Build w...
Dreamweaver CC 2020 is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Dreamweaver customer). Adobe Dreamweaver CC 2020 allows you to... Read more
Adobe Audition 13.0.3 - Professional pos...
Audition is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Audition customer). Adobe Audition empowers you to create and deliver... Read more
Adobe After Effects 17.0.3 - Create prof...
After Effects is available as part of Adobe Creative Cloud for $52.99/month (or $20.99/month for a single app license). The new, more connected After Effects can make the impossible possible. Get... Read more
Audio Hijack 3.6.4 - Record and enhance...
Audio Hijack (was Audio Hijack Pro) drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio... Read more
Eye Candy 7.2.3.96 - 30 professional Pho...
Eye Candy renders realistic effects that are difficult or impossible to achieve in Photoshop alone, such as Fire, Chrome, and the new Lightning. Effects like Animal Fur, Smoke, and Reptile Skin are... Read more
Notability 4.2.2 - Note-taking and annot...
Notability is a powerful note-taker to annotate documents, sketch ideas, record lectures, take notes and more. It combines, typing, handwriting, audio recording, and photos so you can create notes... Read more
Adobe Acrobat Reader 20.006.20034 - View...
Adobe Acrobat Reader allows users to view PDF documents. You may not know what a PDF file is, but you've probably come across one at some point. PDF files are used by companies and even the IRS to... Read more
Adobe Acrobat DC 20.006.20034 - Powerful...
Acrobat DC is available only as a part of Adobe Creative Cloud, and can only be installed and/or updated through Adobe's Creative Cloud app. Adobe Acrobat DC with Adobe Document Cloud services is... Read more
Day One 4.8 - Maintain a daily journal.
Day One is an easy, great-looking way to use a journal / diary / text-logging application. Day One is well designed and extremely focused to encourage you to write more through quick Menu Bar entry,... Read more

Latest Forum Discussions

See All

Marvel Strike Force introduces new brawl...
FoxNext's squad-based RPG Marvel Strike Force is set to receive some fresh characters from the X-Men and Iron Man series. They'll arrive as part of the game's latest update, which follows a sizable spending boycott on the title due to complaints... | Read more »
Speed Dating for Ghosts is a narrative a...
Speed Dating for Ghosts originally released on Steam back 2018, since then it has received honourable mentions for narrative during the Independent Games Festival. Now it's made its way over to iOS devices where it's available as a premium title... | Read more »
Fast-paced multiplayer title Tennis Star...
Tennis Stars: Ultimate Clash is the latest free-to-play tennis title to hit iOS and Android. It's said to be a fairly casual experience, offering easy-to-learn controls and fast-paced, mobile-friendly matches. [Read more] | Read more »
Super Mecha Champions' latest updat...
Super Mecha Champions' latest update sees the addition of a brand new character called R.E.D. Alongside that, there's news about the current season and a series of Emojis that have been added to the game. [Read more] | Read more »
Isle Escape: The House is an upcoming pu...
Isle Escape: The House is an upcoming puzzle game from Simeon Angelov that's intended to serve as an introduction to a saga they're planning on releasing in an episodic fashion. The first chapter is set to release for both iOS and Android on 29th... | Read more »
Company of Heroes, the classic RTS, is n...
Feral Interactive has finally released their highly anticipated iOS version of the strategy classic Company of Heroes. It's available now for iPad as a premium title and has had various tweaks to ensure that it's optimised for touch controls. [... | Read more »
Mario Kart Tour's Vancouver Tour ha...
With Mario Kart Tour's Valentine's Tour now at an end (suspiciously before Valentine's Day has even arrived), it's now time to move on to the all-new and exciting Vancouver Tour. This time around, the featured drivers are Hiker Wario and Aurora... | Read more »
A new PictoQuest update makes it a much...
PictoQuest is a charming little puzzle game, but it left us a little disappointed. The game just didn’t seem to use screen space effectively, to the point that using the touch controls (as opposed to the default virtual d-pad) could lead to errant... | Read more »
Alley is an atmospheric adventure game a...
Alley is an atmospheric adventure game that sees you playing as a young girl trapped in an inescapable nightmare. Surrounded by her worst fears, every step forward for her is a huge challenge that you'll help guide her through using some simple... | Read more »
Fight monsters and collect heroes in Cry...
From Final Fantasy to Chaos Rings, Japanese roleplaying games have found a large and loyal fanbase on mobile devices. If you’re seeking a more under-the-radar JRPG to escape into, Lionsfilm’s Cryptract could be the one. The game has been around... | Read more »

Price Scanner via MacPrices.net

Apple AirPods are on sale for $30 off today
Amazon has new 2019 Apple AirPods (non-Pro models) on sale today for $30 off MSRP, starting at $129. Shipping is free: – AirPods with Wireless Charging Case: $169 $30 off MSRP – AirPods with Charging... Read more
27″ 3.7GHz 6-Core 5K iMac on sale for $2099,...
B&H Photo has the 2019 27″ 3.7GHz 6-Core 5K iMac in stock today and on sale for $200 off Apple’s MSRP. Overnight shipping is free to many locations in the US: – 27″ 3.7GHz 6-Core 5K iMac: $2099 $... Read more
Save up to $250 on a 12.9″ iPad Pros with the...
Apple has Certified Refurbished 12.9″ iPad Pros available on their online store for up to $250 off the cost of new models. Prices start at $849. Each iPad comes with a standard Apple one-year... Read more
Save up to $220 on 11″ iPad Pros with these r...
Apple has Certified Refurbished 11″ iPad Pros available on their online store for up to $220 off the cost of new models. Prices start at $679. Each iPad comes with a standard Apple one-year warranty... Read more
8-Core 27″ iMac Pro available for $4249, Cert...
Apple has Certified Refurbished 27″ 3.2GHz 8-Core iMac Pros available for $4249 including free shipping. Their price is $750 off the cost of new models. A standard Apple one-year warranty is included... Read more
$749 MacBook Airs continue to be available on...
Amazon has the 2017 13″ 1.8GHz/128GB MacBook Air on sale today for only $749 shipped. That’s $250 off Apple’s original MSRP for this model and the cheapest new MacBook available from any Apple... Read more
HomePods on sale for $204 at Other World Comp...
Other World Computing has discounted, new, Apple HomePods on sale for up to $95 off Apple’s MSRP: – HomePod Space Gray: $207.99 $92 off MSRP – HomePod White: $204.99 $95 off MSRP These are the same... Read more
Get a Certified Refurbished iMac at Apple for...
Apple has Certified Refurbished 2019 21″ & 27″ iMacs available starting at $929 and up to $350 off the cost of new models. Apple’s one-year warranty is standard, shipping is free, and each iMac... Read more
A Look Back At The Top 5 Most Read Stories Of...
FEATURE: 02.21.20 The best of the best are now history and we’re not talking about Super Bowl LIV from earlier this month but rather, coverage from the past year (its second and first full one at... Read more
Apple offers wide range of discounted custom...
Save up to $610 on a custom-configured 21″ or 27″ iMac with these Certified Refurbished models available at Apple. Each iMac features a new outer case, free shipping, and includes Apple’s standard 1-... Read more

Jobs Board

Medical Assistant - *Apple* Valley Clinic -...
…professional, quality care to patients in the ambulatory setting at the M Health Fairview Apple Valley Clinic, located in Apple Valley, MN. Join the **M Health Read more
Geek Squad *Apple* Consultation Professiona...
**756636BR** **Job Title:** Geek Squad Apple Consultation Professional **Job Category:** Store Associates **Store NUmber or Department:** 001053-Arundel Mills-Store Read more
Medical Assistant - *Apple* Valley Clinic -...
…professional, quality care to patients in the ambulatory setting at the M Health Fairview Apple Valley Clinic, located in Apple Valley, MN. Join the **M Health Read more
*Apple* Certified Repair Technician - Utah S...
…selected candidate will work in the USU Campus Store Tech Department as an Apple Certified Repair Technician and floor associate. This position is for both summer Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**744429BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000574-Garner-Store **Job Description:** At Best Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.