darling-libobjc2/API

GNUstep Runtime APIs
====================

The GNUstep Objective-C runtime aims to implement all of the APIs defined in
Apple's Objective-C Runtime Reference.  That document should be taken as the
authoritative reference to the majority of the APIs exposed by this runtime.
Any discrepancies between the implementations in this runtime and the
documentation should be regarded as a bug in the runtime.

In addition to these APIs, the runtime also exposes some non-portable APIs.
These are all marked as OBJC_NONPORTABLE in the headers.  Many of these APIs
are also implemented in GNUstep's ObjectiveC2 framework, which uses the GCC
Objective-C runtime for the underlying implementation and provides a portable
set of APIs on top of the GCC runtime structures and functions.

Runtime Capabilities
--------------------

The objc/capabilities.h header defines runtime capabilities.  A copy of this
header is also present in the ObjectiveC2 framework, so you can conditionally
include either version.

You can perform two sorts of checks using this header.  Constants declared in
the header describe capabilities that the runtime may or may not implement.  If
a capability is missing from this header, then it means that you are using an
old version of the runtime, which lacks any knowledge of the header.  You can
use this to refuse to compile with old runtime versions.

You can also use the objc_test_capability() function to test whether a
particular capability is present at run time.  Several of the capabilities are
optional in this runtime, and may not be compiled in to a given install.  If
you require a particular capability, you can use the OBJC_REQUIRE_CAPABILITY()
macro to insert a load function that will abort if the capability is not present.

This shows how to refuse to compile or run with versions of the runtime that do
not support type-dependent dispatch:

	#ifndef OBJC_CAP_TYPE_DEPENDENT_DISPATCH
	#	error Type-dependent dispatch support required!
	#else
	OBJC_REQUIRE_CAPABILITY(OBJC_CAP_TYPE_DEPENDENT_DISPATCH);
	#endif

Typed Selectors
---------------

Like the GCC runtime, this runtime uses typed selectors.  In recent versions,
message lookup is also dependent on the type of the selector by default.  This
can be disabled by not defining the TYPE_DEPENDENT_DISPATCH macro when
building.  When using GNU make, you can get name-dependent dispatch by doing:

	$ gmake tdd=no

This is strongly discouraged.  It will give compatibility with the semantics of
the NeXT, Apple, and GCC runtimes, however these semantics include random stack
corruption from valid code.

There are three functions for dealing with typed selectors.  The first two are
direct equivalents of other functions.

	SEL sel_registerTypedName_np(const char *selName, const char *types);

sel_registerName() will register an untyped selector.  This variant registers a
typed selector, using the specified name and type encoding.

	const char *sel_getType_np(SEL aSel);

This function simply returns the type encoding of the given selector, or NULL for a typed selector.

	unsigned sel_copyTypes_np(const char *selName,
	                          const char **types,
	                          unsigned count);

This function copies *all* of the type encodings for a given selector name.
Generally, there are not many of these.  In a well-written program, there will
be exactly one type encoding for a given selector.  In a typical program, there
will be 1-3.  It is not worth allocating a buffer on the heap for most cases,
so this function is designed to take a stack buffer.

Unlike other functions in the runtime, this always returns the total number of
type encodings, not the number that were found.  This means that you can call
it once with a smallish on-stack buffer and then call it again with a
malloc()'d buffer if there are a lot of encodings for a specific selector, as
follows.

	char *t[16];
	char *types = t;
	unsigned total = sel_copyTypes_np("alloc", types, total);
	if (total > 16)
	{
		types = calloc(sizeof(char*), total);
		sel_copyTypes_np("alloc", types, total);
	}
	// Do stuff with the types.
	if (total > 16)
	{
		free(types);
	}


**Note**: This runtime does not provide any equivalent of the GCC runtime's
sel_get_typed_uid() or sel_get_any_typed_uid().  This is intentional.  It is
impossible to use these functions correctly and they should never have been
made part of the public API.

Message Sending
---------------

For ABI compatibility with the GCC runtime, this runtime implements the
objc_msg_lookup() and objc_msg_lookup_super() functions used to implement
message sending.

The new ABI uses the objc_msg_lookup_sender() function in place of
objc_msg_lookup().  This allows fast proxies and caching of the lookup result
at the callsite.  You can find more a detailed explanation of how this works in
the README file.

This runtime also provides this semi-private function, which can be of use in
implementing parts of the Foundation framework and similar low-level libraries:

	struct objc_slot* objc_get_slot(Class cls, SEL selector);

This looks up the slot for a given selector, without invoking any forwarding
mechanisms.  This is most useful for quickly finding the type encoding of a
method (e.g. for implementing forwarding).  The lookup is as fast as a normal
message lookup, and the types field of the returned slot provides the type
encoding.  This is significantly faster than using class_getInstanceMethod(),
which needs to perform a linear search along a list (O(1) vs O(n)).

Hooks
-----

All of the callback hooks provided by this runtime are described in
objc/hooks.h.