1 /* GNU Objective-C Runtime API - Modern API
2 Copyright (C) 2010-2013 Free Software Foundation, Inc.
3 Contributed by Nicola Pero <nicola.pero@meta-innovation.com>
5 This file is part of GCC.
7 GCC is free software; you can redistribute it and/or modify it
8 under the terms of the GNU General Public License as published by the
9 Free Software Foundation; either version 3, or (at your option) any
12 GCC is distributed in the hope that it will be useful, but WITHOUT
13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
15 License for more details.
17 Under Section 7 of GPL version 3, you are granted additional
18 permissions described in the GCC Runtime Library Exception, version
19 3.1, as published by the Free Software Foundation.
21 You should have received a copy of the GNU General Public License and
22 a copy of the GCC Runtime Library Exception along with this program;
23 see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
24 <http://www.gnu.org/licenses/>. */
26 #ifndef __objc_runtime_INCLUDE_GNU
27 #define __objc_runtime_INCLUDE_GNU
30 This file declares the "modern" GNU Objective-C Runtime API.
32 This API replaced the "traditional" GNU Objective-C Runtime API
33 (which used to be declared in objc/objc-api.h) which is the one
34 supported by older versions of the GNU Objective-C Runtime. The
35 "modern" API is very similar to the API used by the modern
39 #include "objc-decls.h"
43 #endif /* __cplusplus */
45 /* An 'Ivar' represents an instance variable. It holds information
46 about the name, type and offset of the instance variable. */
47 typedef struct objc_ivar
*Ivar
;
49 /* A 'Property' represents a property. It holds information about the
50 name of the property, and its attributes.
52 Compatibility Note: the Apple/NeXT runtime defines this as
53 objc_property_t, so we define it that way as well, but obviously
54 Property is the right name. */
55 typedef struct objc_property
*Property
;
56 typedef struct objc_property
*objc_property_t
;
58 /* A 'Method' represents a method. It holds information about the
59 name, types and the IMP of the method. */
60 typedef struct objc_method
*Method
;
62 /* A 'Category' represents a category. It holds information about the
63 name of the category, the class it belongs to, and the methods,
64 protocols and such like provided by the category. */
65 typedef struct objc_category
*Category
;
67 /* 'Protocol' is defined in objc/objc.h (which is included by this
70 /* Method descriptor returned by introspective Object methods. At the
71 moment, this is really just the first part of the more complete
72 objc_method structure used internally by the runtime. (PS: In the
73 GNU Objective-C Runtime, selectors already include a type, so an
74 objc_method_description does not add much to a SEL. But in other
75 runtimes, that is not the case, which is why
76 objc_method_description exists). */
77 struct objc_method_description
79 SEL name
; /* Selector (name and signature) */
80 char *types
; /* Type encoding */
83 /* The following are used in encode strings to describe the type of
96 #define _C_LNG_LNG 'q'
97 #define _C_ULNG_LNG 'Q'
100 #define _C_LNG_DBL 'D'
106 #define _C_CHARPTR '*'
109 #define _C_UNION_B '('
110 #define _C_UNION_E ')'
111 #define _C_STRUCT_B '{'
112 #define _C_STRUCT_E '}'
113 #define _C_VECTOR '!'
114 #define _C_COMPLEX 'j'
116 /* _C_ATOM is never generated by the compiler. You can treat it as
117 equivalent to "*". */
120 /* The following are used in encode strings to describe some
121 qualifiers of method and ivar types. */
126 #define _C_BYCOPY 'O'
128 #define _C_ONEWAY 'V'
129 #define _C_GCINVISIBLE '|'
131 /* The same when used as flags. */
132 #define _F_CONST 0x01
135 #define _F_INOUT 0x03
136 #define _F_BYCOPY 0x04
137 #define _F_BYREF 0x08
138 #define _F_ONEWAY 0x10
139 #define _F_GCINVISIBLE 0x20
142 /** Implementation: the following functions are defined inline. */
144 /* Return the class of 'object', or Nil if the object is nil. If
145 'object' is a class, the meta class is returned; if 'object' is a
146 meta class, the root meta class is returned (note that this is
147 different from the traditional GNU Objective-C Runtime API function
148 object_get_class(), which for a meta class would return the meta
149 class itself). This function is inline, so it is really fast and
150 should be used instead of accessing object->class_pointer
153 object_getClass (id object
)
156 return object
->class_pointer
;
162 /** Implementation: the following functions are in selector.c. */
164 /* Return the name of a given selector. If 'selector' is NULL, return
165 "<null selector>". */
166 objc_EXPORT
const char *sel_getName (SEL selector
);
168 /* Return the type of a given selector. Return NULL if selector is
171 Compatibility Note: the Apple/NeXT runtime has untyped selectors,
172 so it does not have this function, which is specific to the GNU
174 objc_EXPORT
const char *sel_getTypeEncoding (SEL selector
);
176 /* This is the same as sel_registerName (). Please use
177 sel_registerName () instead. */
178 objc_EXPORT SEL
sel_getUid (const char *name
);
180 /* Register a selector with a given name (but unspecified types). If
181 you know the types, it is better to call sel_registerTypedName().
182 If a selector with this name and no types already exists, it is
183 returned. Note that this function should really be called
184 'objc_registerSelector'. Return NULL if 'name' is NULL. */
185 objc_EXPORT SEL
sel_registerName (const char *name
);
187 /* Register a selector with a given name and types. If a selector
188 with this name and types already exists, it is returned. Note that
189 this function should really be called 'objc_registerTypedSelector',
190 and it's called 'sel_registerTypedName' only for consistency with
191 'sel_registerName'. Return NULL if 'name' is NULL.
193 Compatibility Note: the Apple/NeXT runtime has untyped selectors,
194 so it does not have this function, which is specific to the GNU
196 objc_EXPORT SEL
sel_registerTypedName (const char *name
, const char *type
);
198 /* Return YES if first_selector is the same as second_selector, and NO
200 objc_EXPORT BOOL
sel_isEqual (SEL first_selector
, SEL second_selector
);
202 /* Return all the selectors with the supplied name. In the GNU
203 runtime, selectors are typed and there may be multiple selectors
204 with the same name but a different type. The return value of the
205 function is a pointer to an area, allocated with malloc(), that
206 contains all the selectors with the supplier name known to the
207 runtime. The list is terminated by NULL. Optionally, if you pass
208 a non-NULL 'numberOfReturnedSelectors' pointer, the unsigned int
209 that it points to will be filled with the number of selectors
212 Compatibility Note: the Apple/NeXT runtime has untyped selectors,
213 so it does not have this function, which is specific to the GNU
215 objc_EXPORT SEL
* sel_copyTypedSelectorList (const char *name
,
216 unsigned int *numberOfReturnedSelectors
);
218 /* Return a selector with name 'name' and a non-zero type encoding, if
219 there is a single selector with a type, and with that name,
220 registered with the runtime. If there is no such selector, or if
221 there are multiple selectors with the same name but conflicting
222 types, NULL is returned. Return NULL if 'name' is NULL.
224 This is useful if you have the name of the selector, and would
225 really like to get a selector for it that includes the type
226 encoding. Unfortunately, if the program contains multiple selector
227 with the same name but different types, sel_getTypedSelector can
228 not possibly know which one you need, and so will return NULL.
230 Compatibility Note: the Apple/NeXT runtime has untyped selectors,
231 so it does not have this function, which is specific to the GNU
233 objc_EXPORT SEL
sel_getTypedSelector (const char *name
);
236 /** Implementation: the following functions are in objects.c. */
238 /* Create an instance of class 'class_', adding extraBytes to the size
239 of the returned object. This method allocates the appropriate
240 amount of memory for the instance, initializes it to zero, then
241 calls all the C++ constructors on appropriate C++ instance
242 variables of the instance (if any) (TODO: The C++ constructors bit
243 is not implemented yet). */
244 objc_EXPORT id
class_createInstance (Class class_
, size_t extraBytes
);
246 /* Copy an object and return the copy. extraBytes should be identical
247 to the extraBytes parameter that was passed when creating the
249 objc_EXPORT id
object_copy (id object
, size_t extraBytes
);
251 /* Dispose of an object. This method calls the appropriate C++
252 destructors on appropriate C++ instance variables of the instance
253 (if any) (TODO: This is not implemented yet), then frees the memory
255 objc_EXPORT id
object_dispose (id object
);
257 /* Return the name of the class of 'object'. If 'object' is 'nil',
259 objc_EXPORT
const char * object_getClassName (id object
);
261 /* Change the class of object to be class_. Return the previous class
262 of object. This is currently not really thread-safe. */
263 objc_EXPORT Class
object_setClass (id object
, Class class_
);
266 /** Implementation: the following functions are in ivars.c. */
268 /* Return an instance variable given the class and the instance
269 variable name. This is an expensive function to call, so try to
270 reuse the returned Ivar if you can. */
271 objc_EXPORT Ivar
class_getInstanceVariable (Class class_
, const char *name
);
273 /* Return a class variable given the class and the class variable
274 name. This is an expensive function to call, so try to reuse the
275 returned Ivar if you can.
277 This function always returns NULL since class variables are
278 currently unavailable in Objective-C. */
279 objc_EXPORT Ivar
class_getClassVariable (Class class_
, const char *name
);
281 /* If the object was created in class_createInstance() with some
282 extraBytes, returns a pointer to them. If it was not, then the
283 returned pointer may make no sense. */
284 objc_EXPORT
void * object_getIndexedIvars (id object
);
286 /* Get the value of an instance variable of type 'id'. The function
287 returns the instance variable. To get the value of the instance
288 variable, you should pass as 'returnValue' a pointer to an 'id';
289 the value will be copied there. Note that 'returnValue' is really
290 a 'void *', not a 'void **'. This function really works only with
291 instance variables of type 'id'; for other types of instance
292 variables, access directly the data at (char *)object +
293 ivar_getOffset (ivar). */
294 objc_EXPORT Ivar
object_getInstanceVariable (id object
, const char *name
, void **returnValue
);
296 /* Set the value of an instance variable. The value to set is passed
297 in 'newValue' (which really is an 'id', not a 'void *'). The
298 function returns the instance variable. This function really works
299 only with instance variables of type 'id'; for other types of
300 instance variables, access directly the data at (char *)object +
301 ivar_getOffset (ivar). */
302 objc_EXPORT Ivar
object_setInstanceVariable (id object
, const char *name
, void *newValue
);
304 /* Get the value of an instance variable of type 'id' of the object
305 'object'. This is faster than object_getInstanceVariable if you
306 already have the instance variable because it avoids the expensive
307 call to class_getInstanceVariable that is done by
308 object_getInstanceVariable. */
309 objc_EXPORT id
object_getIvar (id object
, Ivar variable
);
311 /* Set the value of an instance variable of type 'id' of the object
312 'object'. This is faster than object_setInstanceVariable if you
313 already have the instance variable because it avoids the expensive
314 call to class_getInstanceVariable that is done by
315 object_setInstanceVariable. */
316 objc_EXPORT
void object_setIvar (id object
, Ivar variable
, id value
);
318 /* Return the name of the instance variable. Return NULL if
319 'variable' is NULL. */
320 objc_EXPORT
const char * ivar_getName (Ivar variable
);
322 /* Return the offset of the instance variable from the start of the
323 object data. Return 0 if 'variable' is NULL. */
324 objc_EXPORT
ptrdiff_t ivar_getOffset (Ivar variable
);
326 /* Return the type encoding of the variable. Return NULL if
327 'variable' is NULL. */
328 objc_EXPORT
const char * ivar_getTypeEncoding (Ivar variable
);
330 /* Return all the instance variables of the class. The return value
331 of the function is a pointer to an area, allocated with malloc(),
332 that contains all the instance variables of the class. It does not
333 include instance variables of superclasses. The list is terminated
334 by NULL. Optionally, if you pass a non-NULL
335 'numberOfReturnedIvars' pointer, the unsigned int that it points to
336 will be filled with the number of instance variables returned.
337 Return NULL for classes still in construction (ie, allocated using
338 objc_allocatedClassPair() but not yet registered with the runtime
339 using objc_registerClassPair()). */
340 objc_EXPORT Ivar
* class_copyIvarList (Class class_
, unsigned int *numberOfReturnedIvars
);
342 /* Add an instance variable with name 'ivar_name' to class 'class_',
343 where 'class_' is a class in construction that has been created
344 using objc_allocateClassPair() and has not been registered with the
345 runtime using objc_registerClassPair() yet. You can not add
346 instance variables to classes already registered with the runtime.
347 'size' is the size of the instance variable, 'log_2_of_alignment'
348 the alignment as a power of 2 (so 0 means alignment to a 1 byte
349 boundary, 1 means alignment to a 2 byte boundary, 2 means alignment
350 to a 4 byte boundary, etc), and 'type' the type encoding of the
351 variable type. You can use sizeof(), log2(__alignof__()) and
352 @encode() to determine the right 'size', 'alignment' and 'type' for
353 your instance variable. For example, to add an instance variable
354 name "my_variable" and of type 'id', you can use:
356 class_addIvar (class, "my_variable", sizeof (id), log2 ( __alignof__ (id)),
359 Return YES if the variable was added, and NO if not. In
360 particular, return NO if 'class_' is Nil, or a meta-class or a
361 class not in construction. Return Nil also if 'ivar_name' or
362 'type' is NULL, or 'size' is 0.
364 objc_EXPORT BOOL
class_addIvar (Class class_
, const char * ivar_name
, size_t size
,
365 unsigned char log_2_of_alignment
, const char *type
);
367 /* Return the name of the property. Return NULL if 'property' is
369 objc_EXPORT
const char * property_getName (Property property
);
371 /* Return the attributes of the property as a string. Return NULL if
372 'property' is NULL. */
373 objc_EXPORT
const char * property_getAttributes (Property property
);
375 /* Return the property with name 'propertyName' of the class 'class_'.
376 This function returns NULL if the required property can not be
377 found. Return NULL if 'class_' or 'propertyName' is NULL.
379 Note that the traditional ABI does not store the list of properties
380 of a class in a compiled module, so the traditional ABI will always
382 objc_EXPORT Property
class_getProperty (Class class_
, const char *propertyName
);
384 /* Return all the properties of the class. The return value
385 of the function is a pointer to an area, allocated with malloc(),
386 that contains all the properties of the class. It does not
387 include properties of superclasses. The list is terminated
388 by NULL. Optionally, if you pass a non-NULL
389 'numberOfReturnedIvars' pointer, the unsigned int that it points to
390 will be filled with the number of properties returned.
392 Note that the traditional ABI does not store the list of properties
393 of a class in a compiled module, so the traditional ABI will always
394 return an empty list. */
395 objc_EXPORT Property
* class_copyPropertyList
396 (Class class_
, unsigned int *numberOfReturnedProperties
);
398 /* Return the ivar layout for class 'class_'.
400 At the moment this function always returns NULL. */
401 objc_EXPORT
const char * class_getIvarLayout (Class class_
);
403 /* Return the weak ivar layout for class 'class_'.
405 At the moment this function always returns NULL. */
406 objc_EXPORT
const char * class_getWeakIvarLayout (Class class_
);
408 /* Set the ivar layout for class 'class_'.
410 At the moment, this function does nothing. */
411 objc_EXPORT
void class_setIvarLayout (Class class_
, const char *layout
);
413 /* Set the weak ivar layout for class 'class_'.
415 At the moment, this function does nothing. With the GNU runtime,
416 you should use class_ivar_set_gcinvisible () to hide variables from
417 the Garbage Collector. */
418 objc_EXPORT
void class_setWeakIvarLayout (Class class_
, const char *layout
);
421 /** Implementation: the following functions are in class.c. */
423 /* Compatibility Note: The Apple/NeXT runtime does not have
424 objc_get_unknown_class_handler and
425 objc_setGetUnknownClassHandler(). They provide functionality that
426 the traditional GNU Objective-C Runtime API used to provide via the
427 _objc_lookup_class hook. */
429 /* An 'objc_get_unknown_class_handler' function is used by
430 objc_getClass() to get a class that is currently unknown to the
431 compiler. You could use it for example to have the class loaded by
432 dynamically loading a library. 'class_name' is the name of the
433 class. The function should return the Class object if it manages to
434 load the class, and Nil if not. */
435 typedef Class (*objc_get_unknown_class_handler
)(const char *class_name
);
437 /* Sets a new handler function for getting unknown classes (to be used
438 by objc_getClass () and related), and returns the previous one.
439 This function is not safe to call in a multi-threaded environment
440 because other threads may be trying to use the get unknown class
441 handler while you change it! */
443 objc_get_unknown_class_handler
444 objc_setGetUnknownClassHandler (objc_get_unknown_class_handler new_handler
);
446 /* Return the class with name 'name', if it is already registered with
447 the runtime. If it is not registered, and
448 objc_setGetUnknownClassHandler() has been called to set a handler
449 for unknown classes, the handler is called to give it a chance to
450 load the class in some other way. If the class is not known to the
451 runtime and the handler is not set or returns Nil, objc_getClass()
453 objc_EXPORT Class
objc_getClass (const char *name
);
455 /* Return the class with name 'name', if it is already registered with
456 the runtime. Return Nil if not. This function does not call the
457 objc_get_unknown_class_handler function if the class is not
459 objc_EXPORT Class
objc_lookUpClass (const char *name
);
461 /* Return the meta class associated to the class with name 'name', if
462 it is already registered with the runtime. First, it finds the
463 class using objc_getClass(). Then, it returns the associated meta
464 class. If the class could not be found using objc_getClass(),
466 objc_EXPORT Class
objc_getMetaClass (const char *name
);
468 /* This is identical to objc_getClass(), but if the class is not found,
469 it aborts the process instead of returning Nil. */
470 objc_EXPORT Class
objc_getRequiredClass (const char *name
);
472 /* If 'returnValue' is NULL, 'objc_getClassList' returns the number of
473 classes currently registered with the runtime. If 'returnValue' is
474 not NULL, it should be a (Class *) pointer to an area of memory
475 which can contain up to 'maxNumberOfClassesToReturn' Class records.
476 'objc_getClassList' will fill the area pointed to by 'returnValue'
477 with all the Classes registered with the runtime (or up to
478 maxNumberOfClassesToReturn if there are more than
479 maxNumberOfClassesToReturn). The function return value is the
480 number of classes actually returned in 'returnValue'. */
481 objc_EXPORT
int objc_getClassList (Class
*returnValue
, int maxNumberOfClassesToReturn
);
483 /* Compatibility Note: The Apple/NeXT runtime also has
485 Class objc_getFutureClass (const char *name);
486 void objc_setFutureClass (Class class_, const char *name);
488 the documentation is unclear on what they are supposed to do, and
489 the GNU Objective-C Runtime currently does not provide them. */
491 /* Return the name of the class 'class_', or the string "nil" if the
493 objc_EXPORT
const char * class_getName (Class class_
);
495 /* Return YES if 'class_' is a meta class, and NO if not. If 'class_'
496 is Nil, return NO. */
497 objc_EXPORT BOOL
class_isMetaClass (Class class_
);
499 /* Return the superclass of 'class_'. If 'class_' is Nil, or it is a
500 root class, return Nil. This function also works if 'class_' is a
501 class being constructed, that is, a class returned by
502 objc_allocateClassPair() but before it has been registered with the
503 runtime using objc_registerClassPair(). */
504 objc_EXPORT Class
class_getSuperclass (Class class_
);
506 /* Return the 'version' number of the class, which is an integer that
507 can be used to track changes in the class API, methods and
508 variables. If class_ is Nil, return 0. If class_ is not Nil, the
509 version is 0 unless class_setVersion() has been called to set a
512 Please note that internally the version is a long, but the API only
513 allows you to set and retrieve int values. */
514 objc_EXPORT
int class_getVersion (Class class_
);
516 /* Set the 'version' number of the class, which is an integer that can
517 be used to track changes in the class API, methods and variables.
518 If 'class_' is Nil, does nothing.
520 This is typically used internally by "Foundation" libraries such as
521 GNUstep Base to support serialization / deserialization of objects
522 that work across changes in the classes. If you are using such a
523 library, you probably want to use their versioning API, which may
524 be based on this one, but is integrated with the rest of the
527 Please note that internally the version is a long, but the API only
528 allows you to set and retrieve int values. */
529 objc_EXPORT
void class_setVersion (Class class_
, int version
);
531 /* Return the size in bytes (a byte is the size of a char) of an
532 instance of the class. If class_ is Nil, return 0; else it return
533 a non-zero number (since the 'isa' instance variable is required
535 objc_EXPORT
size_t class_getInstanceSize (Class class_
);
537 /* Change the implementation of the method. It also searches all
538 classes for any class implementing the method, and replaces the
539 existing implementation with the new one. For that to work,
540 'method' must be a method returned by class_getInstanceMethod() or
541 class_getClassMethod() as the matching is done by comparing the
542 pointers; in that case, only the implementation in the class is
543 modified. Return the previous implementation that has been
544 replaced. If method or implementation is NULL, do nothing and
547 method_setImplementation (Method method
, IMP implementation
);
549 /* Swap the implementation of two methods in a single, atomic
550 operation. This is equivalent to getting the implementation of
551 each method and then calling method_setImplementation() on the
552 other one. For this to work, the two methods must have been
553 returned by class_getInstanceMethod() or class_getClassMethod().
554 If 'method_a' or 'method_b' is NULL, do nothing. */
556 method_exchangeImplementations (Method method_a
, Method method_b
);
558 /* Create a new class/meta-class pair. This function is called to
559 create a new class at runtime. The class is created with
560 superclass 'superclass' (use 'Nil' to create a new root class) and
561 name 'class_name'. 'extraBytes' can be used to specify some extra
562 space for indexed variables to be added at the end of the class and
563 meta-class objects (it is recommended that you set extraBytes to
564 0). Once you have created the class, it is not usable yet. You
565 need to add any instance variables (by using class_addIvar()), any
566 instance methods (by using class_addMethod()) and any class methods
567 (by using class_addMethod() on the meta-class, as in
568 class_addMethod (object_getClass (class), method)) that are
569 required, and then you need to call objc_registerClassPair() to
570 activate the class. If you need to create a hierarchy of classes,
571 you need to create and register them one at a time. You can not
572 create a new class using another class in construction as
573 superclass. Return Nil if 'class-name' is NULL or if a class with
574 that name already exists or 'superclass' is a class still in
577 Implementation Note: in the GNU runtime, allocating a class pair
578 only creates the structures for the class pair, but does not
579 register anything with the runtime. The class is registered with
580 the runtime only when objc_registerClassPair() is called. In
581 particular, if a class is in construction, objc_getClass() will not
582 find it, the superclass will not know about it,
583 class_getSuperclass() will return Nil and another thread may
584 allocate a class pair with the same name; the conflict will only be
585 detected when the classes are registered with the runtime.
588 objc_allocateClassPair (Class super_class
, const char *class_name
,
591 /* Register a class pair that was created with
592 objc_allocateClassPair(). After you register a class, you can no
593 longer make changes to its instance variables, but you can start
594 creating instances of it. Do nothing if 'class_' is NULL or if it
595 is not a class allocated by objc_allocateClassPair() and still in
598 objc_registerClassPair (Class class_
);
600 /* Dispose of a class pair created using objc_allocateClassPair().
601 Call this function if you started creating a new class with
602 objc_allocateClassPair() but then want to abort the process. You
603 should not access 'class_' after calling this method. Note that if
604 'class_' has already been registered with the runtime via
605 objc_registerClassPair(), this function does nothing; you can only
606 dispose of class pairs that are still being constructed. Do
607 nothing if class is 'Nil' or if 'class_' is not a class being
610 objc_disposeClassPair (Class class_
);
612 /* Compatibility Note: The Apple/NeXT runtime has the function
613 objc_duplicateClass () but it's undocumented. The GNU runtime does
617 /** Implementation: the following functions are in sendmsg.c. */
619 /* Return the instance method with selector 'selector' of class
620 'class_', or NULL if the class (or one of its superclasses) does
621 not implement the method. Return NULL if class_ is Nil or selector
622 is NULL. Calling this function may trigger a call to
623 +resolveInstanceMethod:, but does not return a forwarding
625 objc_EXPORT Method
class_getInstanceMethod (Class class_
, SEL selector
);
627 /* Return the class method with selector 'selector' of class 'class_',
628 or NULL if the class (or one of its superclasses) does not
629 implement the method. Return NULL if class_ is Nil or selector is
630 NULL. Calling this function may trigger a call to
631 +resolveClassMethod:, but does not return a forwarding
633 objc_EXPORT Method
class_getClassMethod (Class class_
, SEL selector
);
635 /* Return the IMP (pointer to the function implementing a method) for
636 the instance method with selector 'selector' in class 'class_'.
637 This is the same routine that is used while messaging, and should
638 be very fast. Note that you most likely would need to cast the
639 return function pointer to a function pointer with the appropriate
640 arguments and return type before calling it. To get a class
641 method, you can pass the meta-class as the class_ argument (ie, use
642 class_getMethodImplementation (object_getClass (class_),
643 selector)). Return NULL if class_ is Nil or selector is NULL.
644 This function first looks for an existing method; if it is not
645 found, it calls +resolveClassMethod: or +resolveInstanceMethod:
646 (depending on whether a class or instance method is being looked
647 up) if it is implemented. If the method returns YES, then it tries
648 the look up again (the assumption being that +resolveClassMethod:
649 or resolveInstanceMethod: will add the method using
650 class_addMethod()). If it is still not found, it returns a
651 forwarding function. */
652 objc_EXPORT IMP
class_getMethodImplementation (Class class_
, SEL selector
);
654 /* Compatibility Note: the Apple/NeXT runtime has the function
655 class_getMethodImplementation_stret () which currently does not
656 exist on the GNU runtime because the messaging implementation is
659 /* Return YES if class 'class_' has an instance method implementing
660 selector 'selector', and NO if not. Return NO if class_ is Nil or
661 selector is NULL. If you need to check a class method, use the
662 meta-class as the class_ argument (ie, use class_respondsToSelector
663 (object_getClass (class_), selector)). */
664 objc_EXPORT BOOL
class_respondsToSelector (Class class_
, SEL selector
);
666 /* Add a method to a class. Use this function to add a new method to
667 a class (potentially overriding a method with the same selector in
668 the superclass); if you want to modify an existing method, use
669 method_setImplementation() instead (or class_replaceMethod ()).
670 This method adds an instance method to 'class_'; to add a class
671 method, get the meta class first, then add the method to the meta
674 class_addMethod (object_getClass (class_), selector,
675 implementation, type);
677 Return YES if the method was added, and NO if not. Do nothing if
678 one of the arguments is NULL. */
679 objc_EXPORT BOOL
class_addMethod (Class class_
, SEL selector
, IMP implementation
,
680 const char *method_types
);
682 /* Replace a method in a class. If the class already have a method
683 with this 'selector', find it and use method_setImplementation() to
684 replace the implementation with 'implementation' (method_types is
685 ignored in that case). If the class does not already have a method
686 with this 'selector', call 'class_addMethod() to add it.
688 Return the previous implementation of the method, or NULL if none
689 was found. Return NULL if any of the arguments is NULL. */
690 objc_EXPORT IMP
class_replaceMethod (Class class_
, SEL selector
, IMP implementation
,
691 const char *method_types
);
694 /** Implementation: the following functions are in methods.c. */
696 /* Return the selector for method 'method'. Return NULL if 'method'
699 This function is misnamed; it should be called
700 'method_getSelector'. To get the actual name, get the selector,
701 then the name from the selector (ie, use sel_getName
702 (method_getName (method))). */
703 objc_EXPORT SEL
method_getName (Method method
);
705 /* Return the IMP of the method. Return NULL if 'method' is NULL. */
706 objc_EXPORT IMP
method_getImplementation (Method method
);
708 /* Return the type encoding of the method. Return NULL if 'method' is
710 objc_EXPORT
const char * method_getTypeEncoding (Method method
);
712 /* Return a method description for the method. Return NULL if
714 objc_EXPORT
struct objc_method_description
* method_getDescription (Method method
);
716 /* Return all the instance methods of the class. The return value of
717 the function is a pointer to an area, allocated with malloc(), that
718 contains all the instance methods of the class. It does not
719 include instance methods of superclasses. The list is terminated
720 by NULL. Optionally, if you pass a non-NULL
721 'numberOfReturnedMethods' pointer, the unsigned int that it points
722 to will be filled with the number of instance methods returned. To
723 get the list of class methods, pass the meta-class in the 'class_'
724 argument, (ie, use class_copyMethodList (object_getClass (class_),
725 &numberOfReturnedMethods)). */
726 objc_EXPORT Method
* class_copyMethodList (Class class_
, unsigned int *numberOfReturnedMethods
);
729 /** Implementation: the following functions are in encoding.c. */
731 /* Return the number of arguments that the method 'method' expects.
732 Note that all methods need two implicit arguments ('self' for the
733 receiver, and '_cmd' for the selector). Return 0 if 'method' is
735 objc_EXPORT
unsigned int method_getNumberOfArguments (Method method
);
737 /* Return the string encoding for the return type of method 'method'.
738 The string is a standard zero-terminated string in an area of
739 memory allocated with malloc(); you should free it with free() when
740 you finish using it. Return an empty string if method is NULL. */
741 objc_EXPORT
char * method_copyReturnType (Method method
);
743 /* Return the string encoding for the argument type of method
744 'method', argument number 'argumentNumber' ('argumentNumber' is 0
745 for self, 1 for _cmd, and 2 or more for the additional arguments if
746 any). The string is a standard zero-terminated string in an area
747 of memory allocated with malloc(); you should free it with free()
748 when you finish using it. Return an empty string if method is NULL
749 or if 'argumentNumber' refers to a non-existing argument. */
750 objc_EXPORT
char * method_copyArgumentType (Method method
, unsigned int argumentNumber
);
752 /* Return the string encoding for the return type of method 'method'.
753 The string is returned by copying it into the supplied
754 'returnValue' string, which is of size 'returnValueSize'. No more
755 than 'returnValueSize' characters are copied; if the encoding is
756 smaller than 'returnValueSize', the rest of 'returnValue' is filled
757 with zeros. If it is bigger, it is truncated (and would not be
758 zero-terminated). You should supply a big enough
759 'returnValueSize'. If the method is NULL, returnValue is set to a
761 objc_EXPORT
void method_getReturnType (Method method
, char *returnValue
,
762 size_t returnValueSize
);
764 /* Return the string encoding for the argument type of method
765 'method', argument number 'argumentNumber' ('argumentNumber' is 0
766 for self, 1 for _cmd, and 2 or more for the additional arguments if
767 any). The string is returned by copying it into the supplied
768 'returnValue' string, which is of size 'returnValueSize'. No more
769 than 'returnValueSize' characters are copied; if the encoding is
770 smaller than 'returnValueSize', the rest of 'returnValue' is filled
771 with zeros. If it is bigger, it is truncated (and would not be
772 zero-terminated). You should supply a big enough
773 'returnValueSize'. If the method is NULL, returnValue is set to a
775 objc_EXPORT
void method_getArgumentType (Method method
, unsigned int argumentNumber
,
776 char *returnValue
, size_t returnValueSize
);
779 /** Implementation: the following functions are in protocols.c. */
781 /* Return the protocol with name 'name', or nil if it the protocol is
782 not known to the runtime. */
783 objc_EXPORT Protocol
*objc_getProtocol (const char *name
);
785 /* Return all the protocols known to the runtime. The return value of
786 the function is a pointer to an area, allocated with malloc(), that
787 contains all the protocols known to the runtime; the list is
788 terminated by NULL. You should free this area using free() once
789 you no longer need it. Optionally, if you pass a non-NULL
790 'numberOfReturnedProtocols' pointer, the unsigned int that it
791 points to will be filled with the number of protocols returned. If
792 there are no protocols known to the runtime, NULL is returned. */
793 objc_EXPORT Protocol
**objc_copyProtocolList (unsigned int *numberOfReturnedProtocols
);
795 /* Add a protocol to a class, and return YES if it was done
796 successfully, and NO if not. At the moment, NO should only happen
797 if class_ or protocol are nil, if the protocol is not a Protocol
798 object or if the class already conforms to the protocol. */
799 objc_EXPORT BOOL
class_addProtocol (Class class_
, Protocol
*protocol
);
801 /* Return YES if the class 'class_' conforms to Protocol 'protocol',
802 and NO if not. This function does not check superclasses; if you
803 want to check for superclasses (in the way that [NSObject
804 +conformsToProtocol:] does) you need to iterate over the class
805 hierarchy using class_getSuperclass(), and call
806 class_conformsToProtocol() for each of them. */
807 objc_EXPORT BOOL
class_conformsToProtocol (Class class_
, Protocol
*protocol
);
809 /* Return all the protocols that the class conforms to. The return
810 value of the function is a pointer to an area, allocated with
811 malloc(), that contains all the protocols formally adopted by the
812 class. It does not include protocols adopted by superclasses. The
813 list is terminated by NULL. Optionally, if you pass a non-NULL
814 'numberOfReturnedProtocols' pointer, the unsigned int that it
815 points to will be filled with the number of protocols returned.
816 This function does not return protocols that superclasses conform
818 objc_EXPORT Protocol
**class_copyProtocolList (Class class_
, unsigned int *numberOfReturnedProtocols
);
820 /* Return YES if protocol 'protocol' conforms to protocol
821 'anotherProtocol', and NO if not. Note that if one of the two
822 protocols is nil, it returns NO. */
823 objc_EXPORT BOOL
protocol_conformsToProtocol (Protocol
*protocol
, Protocol
*anotherProtocol
);
825 /* Return YES if protocol 'protocol' is the same as protocol
826 'anotherProtocol', and 'NO' if not. Note that it returns YES if
827 the two protocols are both nil. */
828 objc_EXPORT BOOL
protocol_isEqual (Protocol
*protocol
, Protocol
*anotherProtocol
);
830 /* Return the name of protocol 'protocol'. If 'protocol' is nil or is
831 not a Protocol, return NULL. */
832 objc_EXPORT
const char *protocol_getName (Protocol
*protocol
);
834 /* Return the method description for the method with selector
835 'selector' in protocol 'protocol'; if 'requiredMethod' is YES, the
836 function searches the list of required methods; if NO, the list of
837 optional methods. If 'instanceMethod' is YES, the function search
838 for an instance method; if NO, for a class method. If there is no
839 matching method, an objc_method_description structure with both
840 name and types set to NULL is returned. This function will only
841 find methods that are directly declared in the protocol itself, not
842 in other protocols that this protocol adopts.
844 Note that the traditional ABI does not store the list of optional
845 methods of a protocol in a compiled module, so the traditional ABI
846 will always return (NULL, NULL) when requiredMethod == NO. */
847 objc_EXPORT
struct objc_method_description
protocol_getMethodDescription (Protocol
*protocol
,
850 BOOL instanceMethod
);
852 /* Return the method descriptions of all the methods of the protocol.
853 The return value of the function is a pointer to an area, allocated
854 with malloc(), that contains all the method descriptions of the
855 methods of the protocol. It does not recursively include methods
856 of the protocols adopted by this protocol. The list is terminated
857 by a NULL objc_method_description (one with both fields set to
858 NULL). Optionally, if you pass a non-NULL
859 'numberOfReturnedMethods' pointer, the unsigned int that it points
860 to will be filled with the number of properties returned.
862 Note that the traditional ABI does not store the list of optional
863 methods of a protocol in a compiled module, so the traditional ABI
864 will always return an empty list if requiredMethod is set to
866 objc_EXPORT
struct objc_method_description
*protocol_copyMethodDescriptionList (Protocol
*protocol
,
869 unsigned int *numberOfReturnedMethods
);
871 /* Return the property with name 'propertyName' of the protocol
872 'protocol'. If 'requiredProperty' is YES, the function searches
873 the list of required properties; if NO, the list of optional
874 properties. If 'instanceProperty' is YES, the function searches
875 the list of instance properties; if NO, the list of class
876 properties. At the moment, optional properties and class
877 properties are not part of the Objective-C language, so both
878 'requiredProperty' and 'instanceProperty' should be set to YES.
879 This function returns NULL if the required property can not be
882 Note that the traditional ABI does not store the list of properties
883 of a protocol in a compiled module, so the traditional ABI will
884 always return NULL. */
885 objc_EXPORT Property
protocol_getProperty (Protocol
*protocol
, const char *propertyName
,
886 BOOL requiredProperty
, BOOL instanceProperty
);
888 /* Return all the properties of the protocol. The return value of the
889 function is a pointer to an area, allocated with malloc(), that
890 contains all the properties of the protocol. It does not
891 recursively include properties of the protocols adopted by this
892 protocol. The list is terminated by NULL. Optionally, if you pass
893 a non-NULL 'numberOfReturnedProperties' pointer, the unsigned int
894 that it points to will be filled with the number of properties
897 Note that the traditional ABI does not store the list of properties
898 of a protocol in a compiled module, so the traditional ABI will
899 always return NULL and store 0 in numberOfReturnedProperties. */
900 objc_EXPORT Property
*protocol_copyPropertyList (Protocol
*protocol
, unsigned int *numberOfReturnedProperties
);
902 /* Return all the protocols that the protocol conforms to. The return
903 value of the function is a pointer to an area, allocated with
904 malloc(), that contains all the protocols formally adopted by the
905 protocol. It does not recursively include protocols adopted by the
906 protocols adopted by this protocol. The list is terminated by
907 NULL. Optionally, if you pass a non-NULL
908 'numberOfReturnedProtocols' pointer, the unsigned int that it
909 points to will be filled with the number of protocols returned. */
910 objc_EXPORT Protocol
**protocol_copyProtocolList (Protocol
*protocol
, unsigned int *numberOfReturnedProtocols
);
913 /** Implementation: the following hook is in init.c. */
915 /* This is a hook which is called by __objc_exec_class every time a
916 class or a category is loaded into the runtime. This may e.g. help
917 a dynamic loader determine the classes that have been loaded when
918 an object file is dynamically linked in. */
919 objc_EXPORT
void (*_objc_load_callback
)(Class _class
, struct objc_category
*category
);
922 /** Implementation: the following functions are in objc-foreach.c. */
924 /* 'objc_enumerationMutation()' is called when a collection is
925 mutated while being "fast enumerated". That is a hard error, and
926 objc_enumerationMutation is called to deal with it. 'collection'
927 is the collection object that was mutated during an enumeration.
929 objc_enumerationMutation() will invoke the mutation handler if any
930 is set. Then, it will abort the program.
932 Compatibility note: the Apple runtime will not abort the program
933 after calling the mutation handler. */
934 objc_EXPORT
void objc_enumerationMutation (id collection
);
936 /* 'objc_set_enumeration_mutation_handler' can be used to set a
937 function that will be called (instead of aborting) when a fast
938 enumeration is mutated during enumeration. The handler will be
939 called with the 'collection' being mutated as the only argument and
940 it should not return; it should either exit the program, or could
941 throw an exception. The recommended implementation is to throw an
942 exception - the user can then use exception handlers to deal with
945 This function is not thread safe (other threads may be trying to
946 invoke the enumeration mutation handler while you are changing it!)
947 and should be called during during the program initialization
948 before threads are started. It is mostly reserved for "Foundation"
949 libraries; in the case of GNUstep, GNUstep Base may be using this
950 function to improve the standard enumeration mutation handling.
951 You probably shouldn't use this function unless you are writing
952 your own Foundation library. */
953 objc_EXPORT
void objc_setEnumerationMutationHandler (void (*handler
)(id
));
955 /* This structure (used during fast enumeration) is automatically
956 defined by the compiler (it is as if this definition was always
957 included in all Objective-C files). Note that it is usually
958 defined again with the name of NSFastEnumeration by "Foundation"
959 libraries such as GNUstep Base. And if NSFastEnumeration is
960 defined, the compiler will use it instead of
961 __objcFastEnumerationState when doing fast enumeration. */
963 struct __objcFastEnumerationState
967 unsigned long *mutationsPtr;
968 unsigned long extra[5];
973 /* Compatibility Note: The Apple/NeXT runtime has the functions
974 objc_copyImageNames (), class_getImageName () and
975 objc_copyClassNamesForImage () but they are undocumented. The GNU
976 runtime does not have them at the moment. */
978 /* Compatibility Note: The Apple/NeXT runtime has the functions
979 objc_setAssociatedObject (), objc_getAssociatedObject (),
980 objc_removeAssociatedObjects () and the objc_AssociationPolicy type
981 and related enum. The GNU runtime does not have them yet.
982 TODO: Implement them. */
984 /* Compatibility Note: The Apple/NeXT runtime has the function
985 objc_setForwardHandler (). The GNU runtime does not have it
986 because messaging (and, in particular, forwarding) works in a
987 different (incompatible) way with the GNU runtime. If you need to
988 customize message forwarding at the Objective-C runtime level (that
989 is, if you are implementing your own "Foundation" library such as
990 GNUstep Base on top of the Objective-C runtime), in objc/message.h
991 there are hooks (that work in the framework of the GNU runtime) to
995 /** Implementation: the following functions are in memory.c. */
997 /* Traditional GNU Objective-C Runtime functions that are used for
998 memory allocation and disposal. These functions are used in the
999 same way as you use malloc, realloc, calloc and free and make sure
1000 that memory allocation works properly with the garbage
1003 Compatibility Note: these functions are not available with the
1004 Apple/NeXT runtime. */
1006 objc_EXPORT
void *objc_malloc(size_t size
);
1008 /* FIXME: Shouldn't the following be called objc_malloc_atomic ? The
1009 GC function is GC_malloc_atomic() which makes sense.
1011 objc_EXPORT
void *objc_atomic_malloc(size_t size
);
1013 objc_EXPORT
void *objc_realloc(void *mem
, size_t size
);
1015 objc_EXPORT
void *objc_calloc(size_t nelem
, size_t size
);
1017 objc_EXPORT
void objc_free(void *mem
);
1020 /** Implementation: the following functions are in gc.c. */
1022 /* The GNU Objective-C Runtime has a different implementation of
1025 Compatibility Note: these functions are not available with the
1026 Apple/NeXT runtime. */
1028 /* Mark the instance variable as inaccessible to the garbage
1030 objc_EXPORT
void class_ivar_set_gcinvisible (Class _class
,
1031 const char* ivarname
,
1035 /** Implementation: the following functions are in encoding.c. */
1037 /* Traditional GNU Objective-C Runtime functions that are currently
1038 used to implement method forwarding.
1040 Compatibility Note: these functions are not available with the
1041 Apple/NeXT runtime. */
1043 /* Return the size of a variable which has the specified 'type'
1045 objc_EXPORT
int objc_sizeof_type (const char *type
);
1047 /* Return the align of a variable which has the specified 'type'
1049 objc_EXPORT
int objc_alignof_type (const char *type
);
1051 /* Return the aligned size of a variable which has the specified
1052 'type' encoding. The aligned size is the size rounded up to the
1053 nearest alignment. */
1054 objc_EXPORT
int objc_aligned_size (const char *type
);
1056 /* Return the promoted size of a variable which has the specified
1057 'type' encoding. This is the size rounded up to the nearest
1058 integral of the wordsize, taken to be the size of a void *. */
1059 objc_EXPORT
int objc_promoted_size (const char *type
);
1062 /* The following functions are used when parsing the type encoding of
1063 methods, to skip over parts that are ignored. They take as
1064 argument a pointer to a location inside the type encoding of a
1065 method (which is a string) and return a new pointer, pointing to a
1066 new location inside the string after having skipped the unwanted
1069 /* Skip some type qualifiers (_C_CONST, _C_IN, etc). These may
1070 eventually precede typespecs occurring in method prototype
1072 objc_EXPORT
const char *objc_skip_type_qualifiers (const char *type
);
1074 /* Skip one typespec element (_C_CLASS, _C_SEL, etc). If the typespec
1075 is prepended by type qualifiers, these are skipped as well. */
1076 objc_EXPORT
const char *objc_skip_typespec (const char *type
);
1078 /* Skip an offset. */
1079 objc_EXPORT
const char *objc_skip_offset (const char *type
);
1081 /* Skip an argument specification (ie, skipping a typespec, which may
1082 include qualifiers, and an offset too). */
1083 objc_EXPORT
const char *objc_skip_argspec (const char *type
);
1085 /* Read type qualifiers (_C_CONST, _C_IN, etc) from string 'type'
1086 (stopping at the first non-type qualifier found) and return an
1087 unsigned int which is the logical OR of all the corresponding flags
1088 (_F_CONST, _F_IN etc). */
1089 objc_EXPORT
unsigned objc_get_type_qualifiers (const char *type
);
1092 /* Note that the following functions work for very simple structures,
1093 but get easily confused by more complicated ones (for example,
1094 containing vectors). A better solution is required. These
1095 functions are likely to change in the next GCC release. */
1097 /* The following three functions can be used to determine how a
1098 structure is laid out by the compiler. For example:
1100 struct objc_struct_layout layout;
1103 objc_layout_structure (type, &layout);
1104 while (objc_layout_structure_next_member (&layout))
1106 int position, align;
1109 objc_layout_structure_get_info (&layout, &position, &align, &type);
1110 printf ("element %d has offset %d, alignment %d\n",
1111 i++, position, align);
1114 These functions are used by objc_sizeof_type and objc_alignof_type
1115 functions to compute the size and alignment of structures. The
1116 previous method of computing the size and alignment of a structure
1117 was not working on some architectures, particularly on AIX, and in
1118 the presence of bitfields inside the structure. */
1119 struct objc_struct_layout
1121 const char *original_type
;
1123 const char *prev_type
;
1124 unsigned int record_size
;
1125 unsigned int record_align
;
1128 objc_EXPORT
void objc_layout_structure (const char *type
,
1129 struct objc_struct_layout
*layout
);
1130 objc_EXPORT BOOL
objc_layout_structure_next_member (struct objc_struct_layout
*layout
);
1131 objc_EXPORT
void objc_layout_finish_structure (struct objc_struct_layout
*layout
,
1133 unsigned int *align
);
1134 objc_EXPORT
void objc_layout_structure_get_info (struct objc_struct_layout
*layout
,
1135 unsigned int *offset
,
1136 unsigned int *align
,
1141 #endif /* __cplusplus */