Objectively
Object oriented framework for C.
Loading...
Searching...
No Matches
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:
Object

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 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 isCancelled (const Operation *self)
 
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 [0]
 The interface type.
 
- Protected Attributes inherited from Object
ObjectInterface * interface [0]
 The interface type.
 

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

◆ data

ident Operation::data

The user data.

Definition at line 81 of file Operation.h.

◆ function

OperationFunction Operation::function

The Operation function.

Definition at line 92 of file Operation.h.

◆ interface

OperationInterface* Operation::interface[0]
protected

The interface type.

Definition at line 64 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 106 of file Operation.h.

◆ isExecuting

bool Operation::isExecuting

true when this Operation is executing, false otherwise.

Definition at line 111 of file Operation.h.

◆ isFinished

bool Operation::isFinished

true when this Operation is finished, false otherwise.

Definition at line 116 of file Operation.h.

◆ object

Object Operation::object

The superclass.

Definition at line 58 of file Operation.h.

Method Details

◆ _Operation()

Class * _Operation ( void  )

The Operation archetype.

Returns
The Operation Class.

Definition at line 243 of file Operation.c.

243 {
244 static Class *clazz;
245 static Once once;
246
247 do_once(&once, {
248 clazz = _initialize(&(const ClassDef) {
249 .name = "Operation",
250 .superclass = _Object(),
251 .instanceSize = sizeof(Operation),
252 .interfaceSize = sizeof(OperationInterface),
253 .initialize = initialize,
254 });
255 });
256
257 return clazz;
258}
static void initialize(Class *clazz)
Definition Array.c:710
Class * _initialize(const ClassDef *def)
Initializes the given Class.
Definition Class.c:151
long Once
The Once type.
Definition Once.h:37
#define do_once(once, block)
Executes the given block at most one time.
Definition Once.h:43
ClassDefs are passed to _initialize via an archetype to initialize a Class.
Definition Class.h:41
The runtime representation of a Class.
Definition Class.h:90
Class * clazz
Every instance of Object begins with a pointer to its Class.
Definition Object.h:55
Class * _Object(void)
The Object archetype.
Definition Object.c:136
An abstraction for discrete units of work, or tasks.
Definition Operation.h:53

◆ addDependency()

void addDependency ( Operation *  self,
Operation *  dependency 
)

Makes this Operation dependent on the completion of dependency.

Parameters
selfThe Operation.
dependencyThe Operation to await.

Definition at line 59 of file Operation.c.

59 {
60
61 assert(dependency);
62 assert(dependency != self);
63
64 assert($((Array *) self->dependencies, indexOfObject, dependency) == -1);
65
66 $(self->dependencies, addObject, dependency);
67}
static void addObject(Array *self, const ident obj)
Definition Array.c:181
static ssize_t indexOfObject(const Array *self, const ident obj)
Definition Array.c:403
Arrays.
Definition Array.h:56

◆ cancel()

void cancel ( Operation *  self)

Cancels this Operation, allowing it to complete immediately.

Parameters
selfThe Operation.
Remarks
An Operation that has not started will not run its function. An Operation that is executing runs to completion, but its function MAY check isCancelled and return early.

Definition at line 73 of file Operation.c.

73 {
74
75 if ($(self, isCancelled) || self->isFinished) {
76 return;
77 }
78
79 __atomic_store_n(&self->isCancelled, true, __ATOMIC_RELEASE);
80
81 if (self->isExecuting == false) {
82 OperationQueue *queue = self->queue;
83 if (queue) {
84 synchronized(queue->condition, {
85 $(queue->condition, signal);
86 });
87 }
88 }
89}
bool isFinished
true when this Operation is finished, false otherwise.
Definition Operation.h:116
bool isExecuting
true when this Operation is executing, false otherwise.
Definition Operation.h:111
OperationQueues provide threads of execution for Operations.

◆ dependencies()

Array * dependencies ( const Operation *  self)
Parameters
selfThe Operation.
Returns
An instantaneous copy of this Operations' dependencies.

Definition at line 95 of file Operation.c.

95 {
96
97 ident dependencies = $((Object *) self->dependencies, copy);
98
99 return (Array *) dependencies;
100}
static Array * dependencies(const Operation *self)
Definition Operation.c:95
void * ident
The identity type, similar to Objective-C id.
Definition Types.h:49
Object is the root Class of The Objectively Class hierarchy.
Definition Object.h:46
Object * copy(const Object *self)
Creates a shallow copy of this Object.
Definition Array.c:84

◆ init()

Operation * init ( Operation *  self)

Initializes this Operation.

Parameters
selfThe Operation.
Returns
The initialized Operation, or NULL on error.
Remarks
Asynchronous subclasses should invoke this initializer.

Definition at line 106 of file Operation.c.

106 {
107
108 self = (Operation *) super(Object, self, init);
109 if (self) {
110
111 self->condition = $(alloc(Condition), init);
112 assert(self->condition);
113
114 self->dependencies = $(alloc(Array), init);
115 assert(self->dependencies);
116 }
117
118 return self;
119}
#define alloc(type)
Allocate and initialize and instance of type.
Definition Class.h:226
#define super(type, obj, method,...)
POSIX Threads conditional variables.
Definition Condition.h:44
Operation * init(Operation *self)
Initializes this Operation.
Definition Operation.c:106

◆ initWithFunction()

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

Initializes a synchronous Operation with the given function.

Parameters
selfThe Operation.
functionThe OperationFunction.
dataThe user data.
Returns
The initialized Operation, or NULL on error.

Definition at line 125 of file Operation.c.

125 {
126
127 self = $(self, init);
128 if (self) {
129 self->function = function;
130 self->data = data;
131 }
132
133 return self;
134}
ident data
The user data.
Definition Operation.h:81
OperationFunction function
The Operation function.
Definition Operation.h:92

◆ isCancelled()

bool isCancelled ( const Operation *  self)
Parameters
selfThe Operation.
Returns
true if this Operation has been cancelled, false otherwise.
Remarks
This MAY be called from any thread, including from the Operation's function while another thread cancels it.

Definition at line 140 of file Operation.c.

140 {
141 return __atomic_load_n(&self->isCancelled, __ATOMIC_ACQUIRE);
142}

◆ isReady()

bool isReady ( const Operation *  self)
Parameters
selfThe Operation.
Returns
true when all criteria for this Operation to start are met.

Definition at line 148 of file Operation.c.

148 {
149
150 if (self->isDispatched || self->isExecuting || self->isFinished) {
151 return false;
152 }
153
154 if ($(self, isCancelled)) {
155 return true;
156 }
157
158 const Array *dependencies = (Array *) self->dependencies;
159 for (size_t i = 0; i < dependencies->count; i++) {
160
161 Operation *dependency = $(dependencies, objectAtIndex, i);
162 if (dependency->isFinished == false) {
163 return false;
164 }
165 }
166
167 return true;
168}
static ident objectAtIndex(const Array *self, size_t index)
Definition Array.c:578
size_t count
The count of elements.
Definition Array.h:72
bool isDispatched
True once an OperationQueue has dispatched this Operation to one of its Threads, so that no other Thr...
Definition Operation.h:106

◆ removeDependency()

void removeDependency ( Operation *  self,
Operation *  dependency 
)

Removes the dependency on dependency.

Parameters
selfThe Operation.
dependencyThe dependency.

◆ start()

void start ( Operation *  self)

Starts this Operation.

Parameters
selfThe 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 185 of file Operation.c.

185 {
186
187 if (self->isFinished || self->isExecuting) {
188 return;
189 }
190
191 if ($(self, isCancelled) == false) {
192 self->isExecuting = true;
193 self->function(self);
194 self->isExecuting = false;
195 }
196
197 self->isFinished = true;
198
199 synchronized(self->condition, {
200 $(self->condition, broadcast);
201 });
202}
static void broadcast(Condition *self)
Definition Condition.c:57

◆ waitUntilFinished()

void waitUntilFinished ( const Operation *  self)

Blocks the current thread until this Operation isFinished.

Parameters
selfThe Operation.

Definition at line 208 of file Operation.c.

208 {
209
210 synchronized(self->condition, {
211 while (self->isFinished == false) {
212 $(self->condition, wait);
213 }
214 });
215}

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