Resources | Resources |



Criteria for choosing interfaces

This section provides information on the relative advantages and uses of the available interfaces and function, including debugging information and performance considerations.

Differences among interfaces and functions

  • The application-layer functions (MALLOC(), REALLOC(), and FREE()) are optimized for Brew MP applicaions and extensions.
  • The IEnv and IHeap1 interfaces are better for writing directly to OS Services APIs, and for running as a service or device driver in OS Services.

    IHeap1 is preferable to IEnv only in applications that require advanced IHeap1-specific functions such as IHeap1_Tag(), IHeap1_Walk(), or IHeap1 _Statistics(). For simple functions like allocating, reallocating or freeing heap, there is no preference for one over the other. IHeap1 supports the same functions, but IEnv provides heap information without the need to search for it.

  • With MALLOC(), the memory block is automatically freed when the application exits. OEM_Malloc() reserves blocks until explicitly freed using OEM_Free().

IEnv functions return error codes only, and their application-layer counterparts return error codes and pointers; thus, these interfaces are not interchangeable. Developers converting code must keep dependencies in mind.

Important considerations

It is important to use the same type of interface or functions when both allocating and freeing a given block of memory. For example, heap space allocated using IEnv should be freed with IEnv; heap space allocated with MALLOC() should be freed with FREE().

Treating memory as an unlimited resource (for example, a browser cache that keeps requesting memory for pages, images, etc.), will eventually starve other applications, making the device less usable and potentially less stable.

Querying IHeap1 from an IEnv is not recommended, because the IEnv object does not support IHeap1. The IEnv object supports IRealloc; it is not possible to query that for IHeap1. It is preferable instead to do a CreateInstance of an IRealloc or a CreateInstance of a classID Realloc, and then query the realloc for IHeap1; for example: [Need to explain in this paragraph how the IHeap1 interface should be created, and show how to QueryInterface() for IHeap1 in both the paragraph and the sample below.]

   nErr = IEnv_CreateInstance(piEnv, AEECLSID_Realloc, (void **)&piRealloc);
   if (AEE_SUCCESS != nErr) {
      IEnv_Free(piEnv, me);
      return nErr;