OperationQueue Struct Reference

#include <OperationQueue.h>

Overview

OperationQueues provide threads of execution for Operations.

Definition at line 44 of file OperationQueue.h.

Inheritance diagram for OperationQueue:

Properties
bool	isSuspended
	When true, the queue will not start any new Operations.
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 *	_OperationQueue (void)
	The OperationQueue archetype.
void	addOperation (OperationQueue *self, Operation *operation)
	Adds an Operation to this queue.
Operation *	addOperationWithFunction (OperationQueue *self, OperationFunction *function, ident data)
	Adds an Operation to this queue.
Operation *	addOperationWithFunction (OperationQueue *self, OperationFunction function, ident data)
void	cancelAllOperations (OperationQueue *self)
	Cancels all pending Operations residing within this Queue.
OperationQueue *	currentQueue (void)
OperationQueue *	init (OperationQueue *self)
	Initializes this OperationQueue as a serial queue.
OperationQueue *	initWithMaxConcurrentOperations (OperationQueue *self, size_t maxConcurrentOperations)
	Initializes this OperationQueue with the given concurrency.
size_t	operationCount (const OperationQueue *self)
Array *	operations (const OperationQueue *self)
void	removeOperation (OperationQueue *self, Operation *operation)
	Removes the Operation from this queue.
void	resume (OperationQueue *self)
	Resumes this queue, allowing it to start Operations again.
void	suspend (OperationQueue *self)
	Suspends this queue, preventing it from starting any new Operations.
void	waitUntilAllOperationsAreFinished (OperationQueue *self)
	Waits until all Operations submitted to this queue have finished.
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
OperationQueueInterface *	interface
	The interface.
Protected Attributes inherited from Object
ObjectInterface *	interface
	The interface.

Property Details

condition

Condition* OperationQueue::condition

A condition signaled on addOperation and removeOperation.

Definition at line 65 of file OperationQueue.h.

interface

OperationQueueInterface* OperationQueue::interface

protected

The interface.

Definition at line 55 of file OperationQueue.h.

isSuspended

bool OperationQueue::isSuspended

When true, the queue will not start any new Operations.

Remarks

Read-only; use suspend and resume, which notify the queue's Threads of the transition.

Definition at line 84 of file OperationQueue.h.

object

Object OperationQueue::object

The superclass.

Definition at line 49 of file OperationQueue.h.

operations

Array* OperationQueue::operations

The Operations.

Definition at line 70 of file OperationQueue.h.

threads

Array* OperationQueue::threads

The backing Threads, one per concurrently executing Operation.

Definition at line 75 of file OperationQueue.h.

Method Details

_OperationQueue()

Class * _OperationQueue

(

void

)

The OperationQueue archetype.

Returns

The OperationQueue Class.

Definition at line 349 of file OperationQueue.c.

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

addOperation()

void addOperation	(	OperationQueue *	self,
		Operation *	operation
	)

Adds an Operation to this queue.

Parameters

self	The OperationQueue.
operation	The Operation to add.

Definition at line 74 of file OperationQueue.c.

                                                                     {
 
  assert(operation);
  assert(operation->isCancelled == false);
  assert(operation->isExecuting == false);
  assert(operation->isFinished == false);
 
  synchronized(self->locals.condition, {
    operation->locals.queue = self;
    $(self->locals.operations, addObject, operation);
    $(self->locals.condition, signal);
  });
}

addOperationWithFunction() [1/2]

Operation * addOperationWithFunction	(	OperationQueue *	self,
		OperationFunction *	function,
		ident	data
	)

Adds an Operation to this queue.

Parameters

self	The OperationQueue.
function	The OperationFunction to add.
data	The user data.

Returns

The Operation, which should be released when no longer required.

addOperationWithFunction() [2/2]

Operation * addOperationWithFunction	(	OperationQueue *	self,
		OperationFunction	function,
		ident	data
	)

Definition at line 92 of file OperationQueue.c.

                                                                                                         {
 
  assert(function);
 
  Operation *operation = $(alloc(Operation), initWithFunction, function, data);
 
  $(self, addOperation, operation);
 
  return operation;
}

cancelAllOperations()

void cancelAllOperations

(

OperationQueue *

self

)

Cancels all pending Operations residing within this Queue.

Parameters

self	The OperationQueue.

Definition at line 107 of file OperationQueue.c.

                                                      {
 
  Array *operations = $(self, operations);
 
  for (size_t i = 0; i < operations->count; i++) {
    $((Operation *) $(operations, objectAtIndex, i), cancel);
  }
 
  release(operations);
}

currentQueue()

OperationQueue * currentQueue

(

void

)

Returns

The current OperationQueue, or NULL if none can be determined.

Remarks

This method should only be called from a synchronous Operation that was dispatched via an OperationQueue. This method uses thread-local storage.

Definition at line 124 of file OperationQueue.c.

                                          {
  return _currentQueue;
}

init()

OperationQueue * init

(

OperationQueue *

self

)

Initializes this OperationQueue as a serial queue.

Parameters

self	The OperationQueue.

Returns

The initialized OperationQueue, or NULL on error.

Remarks

Serial queues run one Operation at a time. Use initWithMaxConcurrentOperations for concurrency.

Definition at line 182 of file OperationQueue.c.

                                                  {
  return $(self, initWithMaxConcurrentOperations, 1);
}

initWithMaxConcurrentOperations()

OperationQueue * initWithMaxConcurrentOperations	(	OperationQueue *	self,
		size_t	maxConcurrentOperations
	)

Initializes this OperationQueue with the given concurrency.

Parameters

self	The OperationQueue.
maxConcurrentOperations	The number of Operations to run concurrently, which MUST be at least one.

Returns

The initialized OperationQueue, or NULL on error.

Definition at line 190 of file OperationQueue.c.

                                                                                                             {
 
  assert(maxConcurrentOperations);
 
  self = (OperationQueue *) super(Object, self, init);
  if (self) {
 
    self->locals.condition = $(alloc(Condition), init);
    assert(self->locals.condition);
 
    self->locals.operations = $(alloc(Array), init);
    assert(self->locals.operations);
 
    self->locals.threads = $(alloc(Array), init);
    assert(self->locals.threads);
 
    for (size_t i = 0; i < maxConcurrentOperations; i++) {
 
      Thread *thread = $(alloc(Thread), initWithFunction, run, self);
      assert(thread);
 
      $(self->locals.threads, addObject, thread);
 
      release(thread);
    }
 
    const Array *threads = (Array *) self->locals.threads;
    for (size_t i = 0; i < threads->count; i++) {
      $((Thread *) $(threads, objectAtIndex, i), start);
    }
  }
 
  return self;
}

operationCount()

size_t operationCount

(

const OperationQueue *

self

)

Parameters

self	The OperationQueue.

Returns

The instantaneous count of this OperationQueue's Operations.

Definition at line 229 of file OperationQueue.c.

                                                         {
 
  size_t count;
 
  synchronized(self->locals.condition, {
    count = ((Array *) self->locals.operations)->count;
  });
 
  return count;
}

operations()

Array * operations

(

const OperationQueue *

self

)

Parameters

self	The OperationQueue.

Returns

An instantaneous copy of this OperationQueue's Operations.

Definition at line 244 of file OperationQueue.c.

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

removeOperation()

void removeOperation	(	OperationQueue *	self,
		Operation *	operation
	)

Removes the Operation from this queue.

Parameters

self	The OperationQueue.
operation	The Operation to remove.

Definition at line 259 of file OperationQueue.c.

                                                                        {
 
  assert(operation);
  assert(operation->isExecuting == false);
 
  synchronized(self->locals.condition, {
    operation->locals.queue = NULL;
    $(self->locals.operations, removeObject, operation);
    $(self->locals.condition, signal);
  });
}

resume()

void resume

(

OperationQueue *

self

)

Resumes this queue, allowing it to start Operations again.

Parameters

self	The OperationQueue.

Definition at line 275 of file OperationQueue.c.

                                         {
 
  synchronized(self->locals.condition, {
    self->isSuspended = false;
    $(self->locals.condition, broadcast);
  });
}

suspend()

void suspend

(

OperationQueue *

self

)

Suspends this queue, preventing it from starting any new Operations.

Parameters

self	The OperationQueue.

Remarks

Operations already executing run to completion.

Definition at line 287 of file OperationQueue.c.

                                          {
 
  synchronized(self->locals.condition, {
    self->isSuspended = true;
  });
}

waitUntilAllOperationsAreFinished()

void waitUntilAllOperationsAreFinished

(

OperationQueue *

self

)

Waits until all Operations submitted to this queue have finished.

Parameters

self	The OperationQueue.

Definition at line 298 of file OperationQueue.c.

                                                                    {
 
  while (true) {
 
    Operation *operation = NULL;
 
    synchronized(self->locals.condition, {
      const Array *operations = (Array *) self->locals.operations;
      if (operations->count) {
        operation = retain($(operations, firstObject));
      }
    });
 
    if (operation == NULL) {
      break;
    }
 
    $(operation, waitUntilFinished);
 
    release(operation);
  }
}

---

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

• Sources/Objectively/OperationQueue.h
• Sources/Objectively/OperationQueue.c