Legacy Document

Inside Macintosh: Mac OS Runtime Architectures /

Chapter 3 - Programming for the CFM-Based Runtime Architecture / Calling the Code Fragment Manager

Preparing Code Fragments

If the fragment is an import library that contains a 'cfrg'0 resource, you can use the Code Fragment Manager's GetSharedLibrary function to prepare the fragment. If the fragment is stored in a disk file, you call the GetDiskFragment function. If the fragment is stored in a resource, you need to place the resource into memory (using normal Resource Manager and Memory Manager routines) and then call the GetMemFragment function. In general, however, you should avoid storing fragments in resources. Resource-based fragments do not gain the benefits of file-based fragments (such as file mapping directly from the file's data fork), so you should use them only when you have no other choice.

For complete information about the Code Fragment Manager routines, see Inside Macintosh: PowerPC System Software. The APIs defined in that book apply for both the PowerPC and CFM-68K implementations.

In general, the overhead involved in preparing the code fragment and later releasing it is not trivial, so you should avoid closing the connection to a prepared fragment (that is, calling CloseConnection) until you are finished using it.

IMPORTANT

When called to prepare a plug-in, the Code Fragment Manager automatically prepares all the fragments that make up the plug-in's closure. That is, if the plug-in imports symbols from an import library, that library is also prepared; you do not have to explicitly prepare the library.

Listing 3-1 shows how to prepare a fragment using GetSharedLibrary.

Listing 3-1 Preparing a fragment using GetSharedLibrary

myErr = GetSharedLibrary(myLibName, KPowerPCCFragArch, kPrivateCFragCopy,
                   &myConnID, (Ptr*)&myMainAddr, myErrName);
if (myErr) {
   AlertUser(myErr);
}

The fragment name is held in myLibName and it is specified to be a PowerPC fragment. The Code Fragment Manager follows its standard search path to find the library. See "Searching for Import Libraries," beginning on page 1-12, for more information on the search procedure.

Note that the preparation fails if the preparation of any of the fragments that make up the closure fails. The error term myErrName then contains the name of the fragment that caused the failure.

Listing 3-2 show how to prepare a disk-based fragment.

Listing 3-2 Preparing a disk-based fragment

myErr = GetDiskFragment(&myFSSpec, 0, kCFragGoesToEOF, myToolName, 
               kPrivateCFragCopy, &myConnID, (Ptr*)&myMainAddr, 
               myErrName);
if (myErr) {
   AlertUser(myErr);
}

Listing 3-3 shows how to prepare a resource-based fragment.

Listing 3-3 Preparing a resource-based fragment

Handle         myHandle;
OSErr          myErr;
ConnectionID   myConnID;
Ptr            myMainAddr;
Str255         myErrName;

myHandle = GetResource('tool', 128);
HLock(myHandle);
myErr = GetMemFragment(*myHandle, GetHandleSize(myHandle), 
               myToolName, kPrivateCFragCopy, &myConnID, 
               (Ptr*)&myMainAddr, myErrName);
if (myErr) {
   AlertUser(myErr);
}

The code in Listing 3-3 places the resource into memory by calling the Resource Manager function GetResource and locks it by calling the Memory Manager procedure HLock. Then it calls GetMemFragment to prepare the fragment. The first parameter passed to GetMemFragment specifies the memory address of the fragment. Because GetResource returns a handle to the resource data, Listing 3-3 dereferences the handle to obtain a pointer to the resource data. To avoid dangling pointers, you need to lock the block of memory before calling GetMemFragment. The constant kPrivateCFragCopy passed as the fourth parameter requests that the Code Fragment Manager allocate a new copy of the fragment's global data section.

Like other fragments a resource-based fragment must remain locked in memory and has separate code and data sections. You have access to the connection ID of the resource-based fragment, so you can call Code Fragment Manager routines like CloseConnection and FindSymbol.

Note

Some PowerPC executable resources are specially written to model a classic 68K stand-alone code resource. These accelerated resources do not have all the freedom of a true fragment. See "Accelerated and Fat Resources," beginning on page 7-4, for information about how to write and call an accelerated resource.