Operation Struct Reference

#include <Operation.h>

Overview

An abstraction for discrete units of work, or tasks.

Operations are typically executed via an OperationQueue.

Definition at line 53 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.
ident	data
	The user data.
OperationFunction	function
	The Operation function.
bool	isCancelled
	true when this Operation has been cancelled, false otherwise.
bool	isDispatched
	True once an OperationQueue has dispatched this Operation to one of its Threads, so that no other Thread also starts it.
bool	isExecuting
	true when this Operation is executing, false otherwise.
bool	isFinished
	true when this Operation is finished, false otherwise.
Object	object
	The superclass.
Properties inherited from Object
Class *	clazz
	Every instance of Object begins with a pointer to its Class.
unsigned int	magic
	A header to allow introspection of Object types.

Methods
Class *	_Operation (void)
	The Operation archetype.
void	addDependency (Operation *self, Operation *dependency)
	Makes this Operation dependent on the completion of dependency.
void	cancel (Operation *self)
	Cancels this Operation, allowing it to complete immediately.
Array *	dependencies (const Operation *self)
Operation *	init (Operation *self)
	Initializes this Operation.
Operation *	initWithFunction (Operation *self, OperationFunction function, ident data)
	Initializes a synchronous Operation with the given function.
bool	isReady (const Operation *self)
void	removeDependency (Operation *self, Operation *dependency)
	Removes the dependency on dependency.
void	start (Operation *self)
	Starts this Operation.
void	waitUntilFinished (const Operation *self)
	Blocks the current thread until this Operation isFinished.
Methods inherited from Object
Class *	_Object (void)
	The Object archetype.
Object *	copy (const Object *self)
	Creates a shallow copy of this Object.
void	dealloc (Object *self)
	Frees all resources held by this Object.
String *	description (const Object *self)
int	hash (const Object *self)
Object *	init (Object *self)
	Initializes this Object.
bool	isEqual (const Object *self, const Object *other)
	Tests equality of the other Object.
bool	isKindOfClass (const Object *self, const Class *clazz)
	Tests for Class hierarchy membership.

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

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 93 of file Operation.h.

condition

Condition* Operation::condition

The Condition enabling waitUntilFinished.

Definition at line 73 of file Operation.h.

data

ident Operation::data

The user data.

Definition at line 98 of file Operation.h.

dependencies

Array* Operation::dependencies

Contains Operations which must finish before this one can start.

Definition at line 78 of file Operation.h.

function

OperationFunction Operation::function

The Operation function.

Definition at line 103 of file Operation.h.

interface

OperationInterface* Operation::interface

protected

The interface.

Definition at line 64 of file Operation.h.

isCancelled

bool Operation::isCancelled

true when this Operation has been cancelled, false otherwise.

Definition at line 108 of file Operation.h.

isDispatched

bool Operation::isDispatched

True once an OperationQueue has dispatched this Operation to one of its Threads, so that no other Thread also starts it.

Definition at line 114 of file Operation.h.

isExecuting

bool Operation::isExecuting

true when this Operation is executing, false otherwise.

Definition at line 119 of file Operation.h.

isFinished

bool Operation::isFinished

true when this Operation is finished, false otherwise.

Definition at line 124 of file Operation.h.

object

Object Operation::object

The superclass.

Definition at line 58 of file Operation.h.

queue

OperationQueue* Operation::queue

The OperationQueue this Operation was added to, if any.

Remarks

Not retained; an OperationQueue retains its Operations. This exists so that cancel can notify the queue, which must re-evaluate because cancelling an Operation makes it ready.

Definition at line 86 of file Operation.h.

Method Details

_Operation()

Class * _Operation

(

void

)

The Operation archetype.

Returns

The Operation Class.

Definition at line 234 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 59 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 73 of file Operation.c.

                                    {
 
  if (self->isCancelled == false) {
    if (self->isFinished == false) {
      if (self->isExecuting == false) {
        self->isCancelled = true;
 
        OperationQueue *queue = self->locals.queue;
        if (queue) {
          synchronized(queue->locals.condition, {
            $(queue->locals.condition, signal);
          });
        }
      }
    }
  }
}

dependencies()

Array * dependencies

(

const Operation *

self

)

Parameters

self	The Operation.

Returns

An instantaneous copy of this Operations' dependencies.

Definition at line 95 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 106 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(Array), 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.
data	The user data.

Returns

The initialized Operation, or NULL on error.

Definition at line 125 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 140 of file Operation.c.

                                           {
 
  if (self->isDispatched || 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.

Asynchronous Operations should override this method and coordinate their own state transitions. This method should not be invoked by super.

Definition at line 177 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);
  });
}

waitUntilFinished()

void waitUntilFinished

(

const Operation *

self

)

Blocks the current thread until this Operation isFinished.

Parameters

self	The Operation.

Definition at line 200 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