Objectively User Guide

Table of Contents

• Declaring a Type
• Implementing a Type
• Using a Type
• Initialization
• Invoking an instance method
• Invoking a Class method
• Overriding a method
• Calling super
• Re-classing an instance
• Managing memory
• Shared instances
• Code Templates

A guide to declaring, implementing, and using your own types with Objectively.

Declaring a Type

Every Objectively type consists of three components:

1. The instance struct — starts with the parent type, then the zero-length interface member, then instance variables:

struct Hello {
    Object object;               // parent (starts-with = single inheritance)
    HelloInterface *interface[0]; // carries a type, occupies no storage
    const char *greeting;
};

The interface member exists only so that $ can read its type with typeof; it holds nothing. The interface itself lives on the Class and is reached through Object::clazz. The member MUST directly follow the parent, where its pointer alignment costs no padding.

2. The interface struct — starts with the parent interface, then method function pointers:

struct HelloInterface {
    ObjectInterface objectInterface;
 
    Hello *(*helloWithGreeting)(const char *greeting);
    Hello *(*initWithGreeting)(Hello *self, const char *greeting);
    void   (*sayHello)(const Hello *self);
};

3. The Class archetype — a single exported function that returns the Class:

OBJECTIVELY_EXPORT Class *_Hello(void);

Implementing a Type

#include <stdio.h>
#include <Objectively.h>
 
#define _Class _Hello
 
static Hello *helloWithGreeting(const char *greeting) {
    return $(alloc(Hello), initWithGreeting, greeting);
}
 
static Hello *initWithGreeting(Hello *self, const char *greeting) {
    self = (Hello *) super(Object, self, init);
    if (self) {
        self->greeting = greeting ?: "Hello World!";
    }
    return self;
}
 
static void sayHello(const Hello *self) {
    printf("%s\n", self->greeting);
}
 
static void initialize(Class *clazz) {
    ((HelloInterface *) clazz->interface)->helloWithGreeting = helloWithGreeting;
    ((HelloInterface *) clazz->interface)->initWithGreeting  = initWithGreeting;
    ((HelloInterface *) clazz->interface)->sayHello          = sayHello;
}
 
Class *_Hello(void) {
    static Class *clazz;
    static Once once;
 
    do_once(&once, {
        clazz = _initialize(&(const ClassDef) {
            .name            = "Hello",
            .superclass      = _Object(),
            .instanceSize    = sizeof(Hello),
            .interfaceSize   = sizeof(HelloInterface),
            .initialize      = initialize,
        });
    });
 
    return clazz;
}
 
#undef _Class

Using a Type

Using your custom type is trivial. Instantiate it like you would any Objectively type.

Hello *hello = $(alloc(Hello), initWithGreeting, "Hello, World!");
 
$(hello, sayHello);
 
release(hello);

See Hello.h and Hello.c for the full source.

Initialization

There is no explicit setup or teardown with Objectively. To instantiate a type, simply call alloc from anywhere in your program. The first time a type is instantiated, its Class initializer, initialize, is called. Use initialize to setup your interface, override methods, or initialize a library your class wraps. When your application terminates, an optional Class destructor, destroy, is also called.

Invoking an instance method

To invoke an instance method, use the $ macro.

$(condition, waitUntilDate, date);

Invoking a Class method

To invoke a Class method, use the $$ macro.

Dictionary *dict = $$(Dictionary, dictionary);

Overriding a method

To override a method, overwrite the function pointer from within your Class' initialize method.

((ObjectInterface *) clazz->interface)->dealloc = dealloc;
((ObjectInterface *) clazz->interface)->isEqual = isEqual;

Calling super

To invoke a supertype's method implementation, use the super macro.

super(Object, self, dealloc);

Re-classing an instance

An instance carries no interface pointer of its own: $, cast, and isKindOfClass all resolve through Object::clazz. Reassigning clazz after allocation therefore changes an instance's behavior and its type identity together, immediately. This permits one-off Classes minted purely for behavior, with no struct, header, or archetype of their own:

static bool resizeHandle_captureEvent(Control *self, const SDL_Event *event) {
    // ...
    return true;
}
 
static void resizeHandle_initialize(Class *clazz) {
    ((ControlInterface *) clazz->interface)->captureEvent = resizeHandle_captureEvent;
}
 
Class *proxy = _initialize(&(const ClassDef) {
    .name          = "Control(resizeHandle)",
    .superclass    = classof(resizeHandle),
    .instanceSize  = classof(resizeHandle)->def.instanceSize,
    .interfaceSize = classof(resizeHandle)->def.interfaceSize,
    .initialize    = resizeHandle_initialize,
});
 
((Object *) resizeHandle)->clazz = proxy;

The new Class inherits every method of the original, since _initialize copies the superclass interface before calling initialize. The instance struct MUST NOT change: a Class minted this way SHOULD reuse the superclass's instanceSize exactly, because the memory has already been allocated.

Managing memory

Objectively uses reference counting to govern object retention. Newly instantiated Objects have a reference count of 1. To retain a strong reference to an Object, call retain(obj). To relinquish it, call release(obj). Once an Object's reference count reaches 0, it is deallocated. Remember to balance every retain with a release.

Shared instances

A shared instance or singleton pattern can be achieved through Class methods and release-on-destroy.

static URLSession *_sharedInstance;
 
static *URLSession sharedInstance(void) {
  static Once once;
 
  do_once(&once, {
    _sharedInstance = $(alloc(URLSession), init);
  });
 
  return _sharedInstance;
}
 
static void destroy(Class *clazz) {
  _sharedInstance = release(_sharedInstance);
}
 
// ...
 
URLSession *session = $$(URLSession, sharedInstance);

Remember to wire up the desctructor in your Class' initialization block. See Once.h for details on do_once.

Code Templates

Objectively ships code templates that cut down the boilerplate of declaring and implementing a type — highly recommended. Install the Xcode template by building the Xcode project, or import the Eclipse CDT templates through the Eclipse CDT preferences.