Objectively

Object oriented framework for C.

Zlib license.

About

Objectively is a cross-platform object oriented framework for the C programming language. Objectively provides rich OO semantics to enable object oriented programming directly in C.

Features

• Windows, macOS, iOS, Android & Linux cross-platform support
• Single-parent inheritance with starts-with struct composition
• Class and instance methods with strongly typed interfaces
• Automatic class loading and lifecycle management
• Automatic memory management with reference counting
• Unicode strings with multibyte character set support
• Collections for Objects and C types: Array, Dictionary, List, Set and more
• JSON parsing, marshaling, and JSONPath queries
• Concurrency: Lock, Condition, Thread, Operation, OperationQueue
• Networking: URLSession, JSONContext & RESTClient

Class Hierarchy

Browse the class hierarchy to navigate the full API.

Declaring a Type

Every Objectively type consists of three components:

1. The instance struct — starts with the parent type, then the interface pointer, then instance variables:

struct Hello {
    Object object;           // parent (starts-with = single inheritance)
    HelloInterface *interface;
    const char *greeting;
};

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),
            .interfaceOffset = offsetof(Hello, interface),
            .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);

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.