Editing Carbon (API)

{{Short description|Application programming interface (API)}}
{{Not to be confused with|Carbon (programming language)}}
{{Infobox software
| name = Carbon
| logo = 
| developer = [[Apple Inc.]]
| discontinued = yes
| latest_release_version = 
| latest_release_date = 
| latest_preview_version = 
| latest_preview_date = 
| programming language = 
| operating_system = [[Classic Mac OS]], [[macOS]]
| genre = 
| license = [[Proprietary software|Proprietary]]
| website = hide
}}

'''Carbon''' is one of two primary [[C (programming language)|C-based]] [[application programming interface]]s (APIs) that were developed by [[Apple Inc.|Apple]] for the [[macOS|Mac OS X]] [[operating system]]. Carbon provided a good degree of [[backward compatibility]] for [[computer program|program]]s that ran on [[Mac OS 8]] and [[Mac OS 9|9]]. Developers could use the Carbon APIs to port (“carbonize”) their [[Classic Mac OS|“classic” Mac]] applications and software to the Mac OS X platform with little effort, compared to [[porting]] the app to the entirely different [[Cocoa (API)|Cocoa]] system, which originated in [[OPENSTEP]]. With the release of the Macintosh's [[macOS Catalina|10.15 (Catalina)]] update, the Carbon API was officially discontinued and removed, leaving Cocoa as the sole primary API for developing modern Mac 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 Mountain Lion|OS X 10.8 Mountain Lion]], which was released on July 24, 2012.

==History==
[[File:Adobe ImageReady 7.0 running on Mac OS X.png|thumb|right|275px| "Carbonized" application [[Adobe Systems]] [[Adobe ImageReady|ImageReady]] v.7.0 running directly on [[macOS|Mac OS X]] version [[Mac OS X v10.2|10.2]]]]

===Classic Mac OS programming===
The [[Classic Mac OS|original Mac OS]] used [[Pascal (programming language)|Pascal]] as its primary development platform, and the APIs were heavily based on Pascal's [[call semantics]]. Much of the [[Macintosh Toolbox]] consisted of [[subroutine|procedure calls]], passing information back and forth between the API and program using a variety of [[data structure]]s based on Pascal's [[variant record]] concept.

Over time, a number of [[object library|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++]]. 

===Rhapsody===
With the purchase of [[NeXT]] in late 1996, Apple developed a new operating system strategy based largely on the existing [[OpenStep#OPENSTEP for Mach|OPENSTEP for Mach]] platform. The new [[Rhapsody (operating system)|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 [[API]]s 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|date=March 2014}} Larger developers like [[Microsoft]] and [[Adobe Systems|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.

===Cocoa and Carbon===
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 [[mutator method|accessor]] [[subroutine]]s on [[opaque data type]]s. This allowed Carbon to support true [[Computer multitasking|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 handler]]s or [[device driver]]s.

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)|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 (programming)|bridging]]'' to reduce this impact.<ref>{{cite web |title=Concepts in Objective-C Programming: Toll-Free Bridging |date=2012 |url=https://developer.apple.com/library/content/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html |website=developer.apple.com |access-date=2017-05-08}}</ref>

As part of this conversion, Apple wrote a new window server and [[2D computer graphics|graphics engine]] from scratch to replace the licence-encumbered [[Display PostScript]]: the [[Quartz (graphics layer)|Quartz]] (which has been called "Display PDF").<ref>{{cite web |last=Siracusa |first=John |date=2000 |url=http://archive.arstechnica.com/reviews/1q00/macos-x-gui/macos-x-gui-4.html |title=Mac OS X Update: Quartz & Aqua |website=archive.arstechnica.com |access-date=2017-05-08}}</ref> Quartz provided C API calls that could be used from either Carbon or Cocoa. The underlying operating system itself was further isolated and released as [[Darwin (operating system)|Darwin]].

===Release and evolution===
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 (software)|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.<ref>{{cite web|title=Apple moving Finder to Cocoa|url=http://www.cnet.com/uk/news/apple-moving-finder-to-cocoa/|website=[[CNET]]|first1=Tom|last1=Krazit|access-date=2015-05-21|date=2008-10-17 |archive-url = https://web.archive.org/web/20150711154619/http://www.cnet.com/uk/news/apple-moving-finder-to-cocoa/ |archive-date = 2015-07-11}}</ref>

The transition to [[64-bit computing|64-bit]] Macintosh applications beginning with [[Mac OS X Leopard|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.<ref>{{cite web|url=https://developer.apple.com/documentation/Carbon/Conceptual/Carbon64BitGuide/Introduction/Introduction.html |archive-url=https://web.archive.org/web/20090611041727/http://developer.apple.com/documentation/Carbon/Conceptual/Carbon64BitGuide/Introduction/Introduction.html |archive-date=2009-06-11 |title=Introduction to 64-Bit Guide for Carbon Developers|author=Apple Inc.}}</ref> 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,<ref>{{cite web|url=https://developer.apple.com/documentation/Carbon/Conceptual/Carbon64BitGuide/PortingTo64Bit/PortingTo64Bit.html#//apple_ref/doc/uid/TP40004381-CH3-SW2 |archive-url = https://web.archive.org/web/20090804014545/http://developer.apple.com/documentation/Carbon/Conceptual/Carbon64BitGuide/PortingTo64Bit/PortingTo64Bit.html |archive-date = 2009-08-04 |work = Modifying Your Application to Use 64-Bit Addressing | title = Choosing a Development Path for Your Carbon User Interface |author = Apple Inc}}</ref><ref>{{Cite web |last=Siracusa |first=John |date=2008-04-03 |title=Rhapsody and blues |url=https://arstechnica.com/staff/2008/04/rhapsody-and-blues/ |access-date=2023-02-05 |website=Ars Technica |language=en-us}}</ref> and further reinforced with its deprecation in 2012.

===Transition to Cocoa===
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]],<ref>{{cite web|url=http://blogs.adobe.com/jnack/2008/04/photoshop_lightroom_and_adobes_64-bit_road.html|title=Photoshop, Lightroom, and Adobe's 64-bit roadmap|author=John Nack |archive-url=https://web.archive.org/web/20150414030843/http://blogs.adobe.com/jnack/2008/04/photoshop_lightroom_and_adobes_64-bit_road.html |archive-date=2015-04-14}}</ref> which was eventually updated to Cocoa in April 2010. This also extended to Apple's own flagship software packages, as [[iTunes]]<ref>{{cite web|url=https://arstechnica.com/apple/news/2010/09/itunes-10-hands-on-snappier-performance-questionable-ui-choices.ars|title=iTunes 10 hands-on: snappier performance, questionable UI choices|author=Chris Foresman |date=September 3, 2010|archive-url=https://web.archive.org/web/20150402183024/http://arstechnica.com/apple/2010/09/itunes-10-hands-on-snappier-performance-questionable-ui-choices/ |archive-date=2015-04-02}}</ref> the Finder application, and [[Final Cut Pro]] (as well as the features in the [[QuickTime]] engine that powers it<ref>{{cite web|url=https://arstechnica.com/apple/reviews/2009/08/mac-os-x-10-6.ars|title=Mac OS X 10.6 Snow Leopard: the Ars Technica review|author=John Siracusa |date=September 2009|archive-url=https://web.archive.org/web/20140713115247/http://arstechnica.com/apple/2009/08/mac-os-x-10-6/ |archive-date=2014-07-13}}</ref>) remained written in Carbon for many years. iTunes, Finder, and Final Cut Pro have since been released in Cocoa versions.

===Deprecation and discontinuation===
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 High Sierra|macOS 10.13 High Sierra]].<ref>{{cite web|url=https://developer.apple.com/news/?id=06282017a|title=64-bit Requirement for Mac Apps|author=Apple Inc.|author-link=Apple Inc.|date=2017-06-28|access-date=2018-02-18|archive-url=https://web.archive.org/web/20180130123005/https://developer.apple.com/news/?id=06282017a|archive-date=2018-01-30}}</ref> [[macOS Catalina|macOS 10.15 Catalina]] officially removed support for 32-bit applications, including all Carbon applications.<ref>{{cite web|url=https://www.macrumors.com/guide/32-bit-mac-apps/|title=32-Bit Apps 'Not Optimized for Your Mac' to Stop Working on macOS Catalina|author=MacRumors|date=June 4, 2019|access-date=August 10, 2019}}</ref>

==Architecture==
Carbon descends from the [[Macintosh Toolbox|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 [[library (computing)|shared library]]), principally <code>Carbon.framework</code>, <code>ApplicationServices.framework</code>, and <code>CoreServices.framework</code>, and in classic Mac OS, it resides in a single shared library named <code>'''CarbonLib'''</code>.

Carbon is not a compatibility box; it is a native API for Mac OS X. It sits roughly alongside Cocoa in an architectural diagram. Carbon apps can use all of the native functionality of Mac OS X, and you can mix Carbon and Cocoa windows in the same process.

Carbon is compatible with all of the several [[object file|executable format]]s available for PowerPC Mac OS. <!-- I recall that XCOFF applications could be launched in classic Mac OS. Did this continue to work in X? -->Binary compatibility between Mac OS X and previous versions requires use of a [[Preferred Executable Format]] file, which Apple never supported in their [[Xcode]] [[integrated development environment|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 (programming language)|C]] API.

Some examples of Carbon Managers:

* File Manager &mdash; manages access to the file system, opening, closing, reading and writing files.
* Resource Manager &mdash; manages access to chunks of data in the resource fork of a file. Examples of resources include icons, sounds, images, templates for widgets, etc.
* Font Manager &mdash; manages [[Typeface|font]]s. Deprecated (as part of [[QuickDraw]]) since [[Mac OS X Tiger|Mac OS X v10.4]], in favor of [[Apple Type Services]] (ATS).
* [[QuickDraw]] &mdash; 2D graphics primitives. Deprecated since [[Mac OS X Tiger|Mac OS X v10.4]], in favor of Quartz 2D.
* Carbon Event Manager <!-- NOT to be confused with Event Manager --> &mdash; converts user and system activity into events that code can recognise and respond to.
* HIObject &mdash; a completely new object-oriented API which brings to Carbon an [[Object-oriented programming|OO]] model for building GUIs. This is available in [[Mac OS X v10.2]] or later, and gives Carbon programmers a more powerful API to work 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 &mdash; 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 &mdash; 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 &mdash; manages creation, positioning, updating, and manipulation of windows. Since Mac OS X v10.2, windows have a root HIView.
* Menu Manager &mdash; 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.

==Event handling==
The Mac Toolbox's Event Manager originally used a [[polling (computer science)|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|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 <code>CFRunLoop</code> 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.

==Timers==
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.

==Open source implementations==
[[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]].<ref>{{cite web |title=gnustep/libs-boron: Boron is the atom that comes before carbon. |url=https://github.com/gnustep/libs-boron |website=GitHub |publisher=GNUstep |date=23 March 2019}}</ref> [[Darling (software)|Darling]] also contains a Carbon implementation. Both implementations are highly incomplete and consist mostly of stub functions.

==See also==
* [[Cocoa (API)|Cocoa]]
* [[Interface Builder]]
* [[Objective-C]]
* [[Xcode]]

==References==
{{Reflist}}

== External links ==

* {{webarchive|url=https://web.archive.org/web/20090420064147/http://developer.apple.com/referencelibrary/Carbon/|date=April 20, 2009|title=Carbon Reference Library (Apple Developer Connection)}}
{{macOS}}
{{Widget toolkits}}
{{Use mdy dates|date=October 2013}}

{{DEFAULTSORT:Carbon (Api)}}
[[Category:Compatibility layers]]
[[Category:MacOS APIs]]
[[Category:Apple Inc. developed frameworks]]