Carbon (API)

Carbon was one of two primary C-based application programming interfaces (APIs) developed by Apple for the macOS (formerly Mac OS X and OS X) operating system. Carbon provided a good degree of backward compatibility for programs that ran on Mac OS 8 and 9. Developers could use the Carbon APIs to port (“carbonize”) their “classic” Mac applications and software to the Mac OS X platform with little effort, compared to porting the app to the entirely different Cocoa system, which originated in OPENSTEP. With the release of macOS 10.15 Catalina, the Carbon API was officially discontinued and removed, leaving Cocoa as the sole primary API for developing macOS applications.

Carbon was an important part of Apple's strategy for bringing Mac OS X to market, offering a path for quick porting of existing software applications, as well as a means of shipping applications that would run on either Mac OS X or the classic Mac OS. As the market has increasingly moved to the Cocoa-based frameworks, especially after the release of iOS, the need for a porting library was reduced. Apple did not create a 64-bit version of Carbon while updating their other frameworks in the 2007 time-frame, and eventually deprecated the entire API in OS X 10.8 Mountain Lion, which was released on July 24, 2012.

The original Mac OS used Pascal as its primary development platform, and the APIs were heavily based on Pascal's call semantics. Much of the Macintosh Toolbox consisted of procedure calls, passing information back and forth between the API and program using a variety of data structures based on Pascal's variant record concept.

Over time, a number of object libraries evolved on the Mac, notably the Object Pascal library MacApp and the THINK C Think Class Library, and later versions of MacApp and CodeWarrior's PowerPlant in C++.

With the purchase of NeXT in late 1996, Apple developed a new operating system strategy based largely on the existing OPENSTEP for Mach platform. The new Rhapsody OS strategy was relatively simple; it retained most of OpenStep's existing object libraries under the name "Yellow Box", ported the existing GUI in OPENSTEP for Mach and made it look more Mac-like, ported several major APIs from the Mac OS to Rhapsody's underlying Unix-like system (notably QuickTime and AppleSearch), and added an emulator known as the "Blue Box" that ran existing Mac OS software.

When this plan was revealed at the Worldwide Developers Conference (WWDC) in 1997 there was some push-back from existing Mac OS developers who were upset that their code bases would be effectively locked into an emulator that was unlikely to ever be updated. They took to calling the Blue Box the "penalty box".^{[citation needed]} Larger developers like Microsoft and Adobe balked outright, and refused to consider porting to OpenStep, which was so different from the existing Mac OS that there was little or no compatibility.

Apple took these concerns to heart. When Steve Jobs announced Apple's change in direction at the next WWDC in 1998, he stated that "what developers really wanted was a modern version of the Mac OS, and Apple [was] going to deliver it".

The original Rhapsody concept, with only the Blue Box for running existing Mac OS software, was eventually released in 1999 as Mac OS X Server 1.0. This was the only release based on the original Rhapsody concept.

In order to offer a real and well supported upgrade path for existing Mac OS code bases, Apple introduced the Carbon system. Carbon consists of many libraries and functions that offer a Mac-like API, but running on top of the underlying Unix-like OS, rather than a copy of the Mac OS running in emulation. The Carbon libraries are extensively cleaned up, modernized and better "protected". While the Mac OS was filled with APIs that shared memory to pass data, under Carbon all such access was re-implemented using accessor subroutines on opaque data types. This allowed Carbon to support true multitasking and memory protection, features Mac developers had been requesting for a decade. Other changes from the pre-existing API removed features which were conceptually incompatible with Mac OS X, or simply obsolete. For example, applications could no longer install interrupt handlers or device drivers.

In order to support Carbon, the entire Rhapsody model changed. Whereas Rhapsody would effectively be OpenStep with an emulator, under the new system both the OpenStep and Carbon API would, where possible, share common code. To do this, many of the useful bits of code from the lower-levels of the OpenStep system, written in Objective-C and known as Foundation, were re-implemented in pure C. This code became known as Core Foundation, or CF for short. A version of the Yellow Box ported to call CF became the new Cocoa API, and the Mac-like calls of Carbon also called the same functions. Under the new system, Carbon and Cocoa were peers. This conversion would normally have slowed the performance of Cocoa as the object methods called into the underlying C libraries, but Apple used a technique they called toll-free bridging to reduce this impact.^[1]

As part of this conversion, Apple also ported the graphics engine from the licence-encumbered Display PostScript to the licence-free Quartz (which has been called "Display PDF").^[2] Quartz provided native calls that could be used from either Carbon or Cocoa, as well as offering Java 2D-like interfaces as well. The underlying operating system itself was further isolated and released as Darwin.

Carbon was introduced in incomplete form in 2000, as a shared library backward-compatible with 1997's Mac OS 8.1. This version allowed developers to port their code to Carbon without losing the ability for those programs to run on existing Mac OS machines. Porting to Carbon became known as "Carbonization". Official Mac OS X support arrived in 2001 with the release of Mac OS X v10.0, the first public version of the new OS. Carbon was very widely used in early versions of Mac OS X by almost all major software houses, even by Apple. The Finder, for instance, remained a Carbon application for many years, only being ported to Cocoa with the release of Mac OS X 10.6 in 2009.^[3]

The transition to 64-bit Macintosh applications beginning with Mac OS X v10.5, released October 26, 2007, brought the first major limitations to Carbon. Apple does not provide compatibility between the Macintosh graphical user interface and the C programming language in the 64-bit environment, instead requiring the use of the Objective-C dialect with the Cocoa API.^[4] Many commentaries took this to be the first sign of Carbon's eventual disappearance, a position that was re-enforced when Apple stated no new major additions would be added to the Carbon system,^[5][6] and further reinforced with its deprecation in 2012.

Despite the purported advantages of Cocoa, the need to rewrite large amounts of legacy code slowed the transition of Carbon-based applications, famously with Adobe Photoshop,^[7] which was eventually updated to Cocoa in April 2010. This also extended to Apple's own flagship software packages, as iTunes^[8] and Final Cut Pro (as well as the features in the QuickTime engine that powers it^[9]) remained written in Carbon for many years. Both iTunes and Final Cut Pro X have since been released in Cocoa versions.

In 2012, with the release of OS X 10.8 Mountain Lion, most Carbon APIs were considered deprecated. The APIs were still accessible to developers and all Carbon applications still ran, but the APIs would no longer be updated. On June 28, 2017, Apple announced that 32-bit software for macOS, such as all Carbon applications, would no longer be supported “without compromise” on versions of macOS after macOS 10.13 High Sierra.^[10] macOS 10.15 Catalina officially removed support for 32-bit applications, including all Carbon applications.^[11]

Carbon descends from the Toolbox, and as such, is composed of "Managers". Each Manager is a functionally related API, defining sets of data structures and functions to manipulate them. Managers are often interdependent or layered. Carbon consists of a broad set of functions for managing files, memory, data, the user interface, and other system services. It is implemented as any other API: in macOS, it is spread over several frameworks (each a structure built around a shared library), principally Carbon.framework, ApplicationServices.framework, and CoreServices.framework, and in classic Mac OS, it resides in a single shared library named CarbonLib.

As an umbrella term encompassing all C-language API procedures accessing Mac-specific functionality, Carbon is not designed as a discrete system. Rather, it opens nearly all the functionality of macOS to developers who do not know the Objective-C language required for the broadly equivalent Cocoa API.^[12]

Carbon is compatible with all of the several executable formats available for PowerPC Mac OS. Binary compatibility between Mac OS X and previous versions requires use of a Preferred Executable Format file, which Apple never supported in their Xcode IDE.

Newer parts of Carbon tend to be much more object-oriented in their conception, most of them based on Core Foundation. Some Managers, such as the HIView Manager (a superset of the Control Manager), are implemented in C++, but Carbon remains a C API.

Some examples of Carbon Managers:

• File Manager — manages access to the file system, opening, closing, reading and writing files.
• Resource Manager — manages access to resources, which are predefined chunks of data a program may require. Calls File Manager to read and write resources from disk files. Examples of resources include icons, sounds, images, templates for widgets, etc.
• Font Manager — manages fonts. Deprecated (as part of QuickDraw) since Mac OS X v10.4, in favor of Apple Type Services (ATS).
• QuickDraw — 2D graphics primitives. Deprecated since Mac OS X v10.4, in favor of Quartz 2D.
• Carbon Event Manager — converts user and system activity into events that code can recognise and respond to.
• HIObject — a completely new object-oriented API which brings to Carbon an OO model for building GUIs. HIToolbox in Mac OS Classic and Copland^[13] relied on abandoned IBM System Object Model, so Carbon had to provide quick-and-dirty replacement to enable porting of legacy code. This is available in Mac OS X v10.2 or later, and gives Carbon programmers some of the tools that Cocoa developers have long been familiar with. Starting with Mac OS X v10.2, HIObject is the base class for all GUI elements in Carbon. HIView is supported by Interface Builder, part of Apple's developer tools. Traditionally GUI architectures of this sort have been left to third-party application frameworks to provide. Starting with Mac OS X v10.4, HIObjects are NSObjects and inherit the ability to be serialized into data streams for transport or saving to disk.
• HITheme — uses QuickDraw and Quartz to render graphical user interface (GUI) elements to the screen. HITheme was introduced in Mac OS X v10.3, and Appearance Manager is a compatibility layer on top of HITheme since that version.
• HIView Manager — manages creation, drawing, hit-testing, and manipulation of controls. Since Mac OS X v10.2, all controls are HIViews. In Mac OS X v10.4, the Control Manager was renamed HIView Manager.
• Window Manager — manages creation, positioning, updating, and manipulation of windows. Since Mac OS X v10.2, windows have a root HIView.
• Menu Manager — manages creation, selection, and manipulation of menus. Since Mac OS X v10.2, menus are HIObjects. Since Mac OS X v10.3, menu content may be drawn using HIViews, and all standard menus use HIViews to draw.

The Mac Toolbox's Event Manager originally used a polling model for application design. The application's main event loop asks the Event Manager for an event using GetNextEvent. If there is an event in the queue, the Event Manager passes it back to the application, where it is handled, otherwise it returns immediately. This behavior is called "busy-waiting", running the event loop unnecessarily. Busy-waiting reduces the amount of CPU time available for other applications and decreases battery power on laptops. The classic Event Manager dates from the original Mac OS in 1984, when whatever application was running was guaranteed to be the only application running, and where power management was not a concern.

With the advent of MultiFinder and the ability to run more than one application simultaneously came a new Event Manager call, WaitNextEvent, which allows an application to specify a sleep interval. One easy trick for legacy code to adopt a more efficient model without major changes to its source code is simply to set the sleep parameter passed to WaitNextEvent to a very large value—on macOS, this puts the thread to sleep whenever there is nothing to do, and only returns an event when there is one to process. In this way, the polling model is quickly inverted to become equivalent to the callback model, with the application performing its own event dispatching in the original manner. There are loopholes, though. For one, the legacy toolbox call ModalDialog, for example, calls the older GetNextEvent function internally, resulting in polling in a tight loop without blocking.

Carbon introduces a replacement system, called the Carbon Event Manager. (The original Event Manager still exists for compatibility with legacy applications). Carbon Event Manager provides the event loop for the developer (based on Core Foundation's CFRunLoop in the current implementation); the developer sets up event handlers and enters the event loop in the main function, and waits for Carbon Event Manager to dispatch events to the application.

In the classic Mac OS, there was no operating system support for application level timers (the lower level Time Manager was available, but it executed timer callbacks at interrupt time, during which calls could not be safely made to most Toolbox routines). Timers were usually left to application developers to implement, and this was usually done by counting elapsed time during the idle event - that is, an event that was returned by WaitNextEvent when any other event wasn't available. In order for such timers to have reasonable resolution, developers could not afford WaitNextEvent to delay too long, and so low "sleep" parameters were usually set. This results in highly inefficient scheduling behavior, since the thread will not sleep for very long, instead repeatedly waking to return these idle events. Apple added timer support to Carbon to address this problem—the system can schedule timers with great efficiency.

GNUstep contains an implementation of the Carbon API called Boron. It aims to be compatible with non-deprecated parts of ApplicationServices and CoreServices. The name derives the fact that Boron comes before Carbon on the periodic table of elements.^[14] Darling also contains a Carbon implementation. Both implementations are highly incomplete and consist mostly of stub functions.

• Cocoa
• Interface Builder
• Objective-C
• Xcode

• Carbon Reference Library (Apple Developer Connection) at the Wayback Machine (archived April 20, 2009)