#include <Operation.h>

Overview

An abstraction for discrete units of work, or tasks.

Operations are typically executed via an OperationQueue.

Definition at line 50 of file Operation.h.

Inheritance diagram for Operation:

Properties
_Bool	asynchronous
	If `true`, this Operation will be expected to coordinate its own concurrency and internal state management by overriding `start`. More...

ident	data
	The user data. More...

OperationFunction	function
	The Operation function. More...

_Bool	isCancelled
	`true` when this Operation has been cancelled, `false` otherwise. More...

_Bool	isExecuting
	`true` when this Operation is executing, `false` otherwise. More...

_Bool	isFinished
	`true` when this Operation is finished, `false` otherwise. More...

Object	object
	The superclass. More...

Condition *	condition
	The Condition enabling `waitUntilFinished`. More...

MutableArray *	dependencies
	Contains Operations which must finish before this one can start. More...

Properties inherited from Object
Class *	clazz
	Every instance of Object begins with a pointer to its Class. More...

Methods
Class *	_Operation (void)
	The Operation archetype. More...

void	addDependency (Operation self, Operation dependency)
	Makes this Operation dependent on the completion of `dependency`. More...

void	cancel (Operation *self)
	Cancels this Operation, allowing it to complete immediately. More...

Array *	dependencies (const Operation *self)

Operation *	init (Operation *self)
	Initializes this Operation. More...

Operation *	initWithFunction (Operation *self, OperationFunction function, ident data)
	Initializes a synchronous Operation with the given `function`. More...

_Bool	isReady (const Operation *self)

void	removeDependency (Operation self, Operation dependency)
	Removes the dependency on `dependency`. More...

void	start (Operation *self)
	Starts this Operation. More...

void	waitUntilFinished (const Operation *self)
	Blocks the current thread until this Operation `isFinished`. More...

Methods inherited from Object
Class *	_Object (void)
	The Object archetype. More...

Object *	copy (const Object *self)
	Creates a shallow copy of this Object. More...

void	dealloc (Object *self)
	Frees all resources held by this Object. More...

String *	description (const Object *self)

int	hash (const Object *self)

Object *	init (Object *self)
	Initializes this Object. More...

_Bool	isEqual (const Object self, const Object other)
	Tests equality of the other Object. More...

_Bool	isKindOfClass (const Object self, const Class clazz)
	Tests for Class hierarchy membership. More...

Protected Attributes
OperationInterface *	interface
	The interface. More...

Protected Attributes inherited from Object
ObjectInterface *	interface
	The interface. More...

Property Details

◆ asynchronous

_Bool Operation::asynchronous

If true, this Operation will be expected to coordinate its own concurrency and internal state management by overriding start.

Definition at line 84 of file Operation.h.

◆ condition

Condition* Operation::condition

The Condition enabling waitUntilFinished.

Definition at line 71 of file Operation.h.

◆ data

ident Operation::data ( void )

The user data.

Definition at line 89 of file Operation.h.

◆ dependencies

MutableArray* Operation::dependencies

Contains Operations which must finish before this one can start.

Definition at line 76 of file Operation.h.

◆ function

OperationFunction Operation::function

The Operation function.

Definition at line 94 of file Operation.h.

◆ interface

OperationInterface* Operation::interface

protected

The interface.

Definition at line 61 of file Operation.h.

◆ isCancelled

_Bool Operation::isCancelled

true when this Operation has been cancelled, false otherwise.

Definition at line 99 of file Operation.h.

◆ isExecuting

_Bool Operation::isExecuting

true when this Operation is executing, false otherwise.

Definition at line 104 of file Operation.h.

◆ isFinished

_Bool Operation::isFinished

true when this Operation is finished, false otherwise.

Definition at line 109 of file Operation.h.

◆ object

Object Operation::object

The superclass.

Definition at line 55 of file Operation.h.

Method Details

◆ _Operation()

Class * _Operation ( void )

The Operation archetype.

Returns: The Operation Class.

Definition at line 233 of file Operation.c.

                        {
    static Class *clazz;
    static Once once;
 
    do_once(&once, {
        clazz = _initialize(&(const ClassDef) {
            .name = "Operation",
            .superclass = _Object(),
            .instanceSize = sizeof(Operation),
            .interfaceOffset = offsetof(Operation, interface),
            .interfaceSize = sizeof(OperationInterface),
            .initialize = initialize,
        });
    });
 
    return clazz;
}

◆ addDependency()

void addDependency	(	Operation *	self,
		Operation *	dependency
	)

Makes this Operation dependent on the completion of dependency.

Parameters

self	The Operation.
dependency	The Operation to await.

Definition at line 60 of file Operation.c.

                                                                  {
 
    assert(dependency);
    assert(dependency != self);
 
    assert($((Array *) self->locals.dependencies, indexOfObject, dependency) == -1);
 
    $(self->locals.dependencies, addObject, dependency);
}

◆ cancel()

void cancel ( Operation * self )

Cancels this Operation, allowing it to complete immediately.

Parameters

self	The Operation.

Definition at line 74 of file Operation.c.

                                    {
 
    if (self->isCancelled == false) {
        if (self->isFinished == false) {
            if (self->isExecuting == false) {
                self->isCancelled = true;
            }
        }
    }
}

◆ dependencies()

Array * dependencies ( const Operation * self )

Parameters

self	The Operation.

Returns: An instantaneous copy of this Operations' dependencies.

Definition at line 89 of file Operation.c.

                                                  {
 
    ident dependencies = $((Object *) self->locals.dependencies, copy);
 
    return (Array *) dependencies;
}

◆ init()

Operation * init ( Operation * self )

Initializes this Operation.

Parameters

self	The Operation.

Returns: The initialized Operation, or NULL on error.

Remarks: Asynchronous subclasses should invoke this initializer.

Definition at line 100 of file Operation.c.

                                        {
 
    self = (Operation *) super(Object, self, init);
    if (self) {
 
        self->locals.condition = $(alloc(Condition), init);
        assert(self->locals.condition);
 
        self->locals.dependencies = $(alloc(MutableArray), init);
        assert(self->locals.dependencies);
    }
 
    return self;
}

◆ initWithFunction()

Operation * initWithFunction	(	Operation *	self,
		OperationFunction	function,
		ident	data
	)

Initializes a synchronous Operation with the given function.

Parameters

self	The Operation.
function	The OperationFunction to perform
data	The user data.

Returns: The initialized Operation, or NULL on error.

Definition at line 119 of file Operation.c.

                                                                                            {
 
    self = $(self, init);
    if (self) {
        self->function = function;
        self->data = data;
    }
 
    return self;
}

◆ isReady()

_Bool isReady ( const Operation * self )

Parameters

self	The Operation.

Returns: true when all criteria for this Operation to start are met.

Definition at line 134 of file Operation.c.

                                            {
 
    if (self->isExecuting || self->isFinished) {
        return false;
    }
 
    if (self->isCancelled) {
        return true;
    }
 
    const Array *dependencies = (Array *) self->locals.dependencies;
    for (size_t i = 0; i < dependencies->count; i++) {
 
        Operation *dependency = $(dependencies, objectAtIndex, i);
        if (dependency->isFinished == false) {
            return false;
        }
    }
 
    return true;
}

◆ removeDependency()

void removeDependency	(	Operation *	self,
		Operation *	dependency
	)

Removes the dependency on dependency.

Parameters

self	The Operation.
dependency	The dependency.

◆ start()

void start ( Operation * self )

Starts this Operation.

Parameters

self	The Operation.

Remarks: The default implementation of this method checks the state of the Operation and, if all criteria are met, dispatches the configured function synchronously. When this method returns, the Operation isFinished and has removed itself from any queues it belonged to.; Asynchronous Operations should override this method and coordinate their own state transitions and queue removal. This method should not be invoked by super.

Definition at line 171 of file Operation.c.

                                   {
 
    if (self->isFinished || self->isExecuting) {
        return;
    }
 
    if (self->isCancelled == false) {
        self->isExecuting = true;
        self->function(self);
        self->isExecuting = false;
    }
 
    self->isFinished = true;
 
    synchronized(self->locals.condition, {
        $(self->locals.condition, broadcast);
    });
 
    OperationQueue *currentQueue = $$(OperationQueue, currentQueue);
    if (currentQueue) {
        $(currentQueue, removeOperation, self);
    }
}

◆ waitUntilFinished()

void waitUntilFinished ( const Operation * self )

Blocks the current thread until this Operation isFinished.

Parameters

self	The Operation.

Definition at line 199 of file Operation.c.

                                                     {
 
    synchronized(self->locals.condition, {
        while (self->isFinished == false) {
            $(self->locals.condition, wait);
        }
    });
}

The documentation for this struct was generated from the following files:

Sources/Objectively/Operation.h
Sources/Objectively/Operation.c

Overview

Properties

Methods

Protected Attributes

Property Details

◆ asynchronous

◆ condition

◆ data

◆ dependencies

◆ function

◆ interface

◆ isCancelled

◆ isExecuting

◆ isFinished

◆ object

Method Details

◆ _Operation()

◆ addDependency()

◆ cancel()

◆ dependencies()

◆ init()

◆ initWithFunction()

◆ isReady()

◆ removeDependency()

◆ start()

◆ waitUntilFinished()