ThreadPool Struct Reference

#include <ThreadPool.h>

Overview

A fixed set of Threads that run ThreadFunctions on behalf of the caller.

Submitted functions wait in a first-in, first-out queue until a Thread is free. Each ThreadFunction receives a Thread whose data is the user data that was submitted with the function.

Deallocating a ThreadPool sets isCancelled on its Threads, which then run the functions still in the queue before they exit. A long-running function MAY check isCancelled to return early. A function MUST NOT cancel the Thread that it is given.

A function runs on the calling thread, with a Thread that is never started and never cancelled, in two cases: ThreadPool::wait is called while the function is still in the queue, or the size of the ThreadPool is 0. A function MUST NOT join, kill or detach that Thread, and MUST NOT rely on isCancelled alone to return, because it is never set.

Remarks

A ThreadPool MUST NOT be deallocated by one of its own Threads.

Definition at line 64 of file ThreadPool.h.

Inheritance diagram for ThreadPool:

Properties
Object	object
	The superclass.
size_t	size
	The number of Threads.
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 *	_ThreadPool (void)
	The ThreadPool archetype.
void	detach (ThreadPool *self, ThreadFunction function, ident data)
	Queues function without a handle to wait on.
ThreadPoolWork *	execute (ThreadPool *self, ThreadFunction function, ident data)
	Queues function, returning a handle to wait on.
ThreadPool *	init (ThreadPool *self)
	Initializes this ThreadPool with one Thread per online processor.
ThreadPool *	initWithSize (ThreadPool *self, size_t size)
	Initializes this ThreadPool with the specified number of Threads.
ident	wait (ThreadPool *self, ThreadPoolWork *work)
	Waits for the specified ThreadPoolWork to finish, and frees it.
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
ThreadPoolInterface *	interface [0]
	The interface type.
Protected Attributes inherited from Object
ObjectInterface *	interface [0]
	The interface type.

Property Details

interface

ThreadPoolInterface* ThreadPool::interface[0]

protected

The interface type.

Definition at line 75 of file ThreadPool.h.

object

Object ThreadPool::object

The superclass.

Definition at line 69 of file ThreadPool.h.

size

size_t ThreadPool::size

The number of Threads.

Remarks

Read-only.

Definition at line 93 of file ThreadPool.h.

Method Details

_ThreadPool()

Class * _ThreadPool

(

void

)

The ThreadPool archetype.

Returns

The ThreadPool Class.

Definition at line 375 of file ThreadPool.c.

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

detach()

void detach	(	ThreadPool *	self,
		ThreadFunction	function,
		ident	data
	)

Queues function without a handle to wait on.

Parameters

self	The ThreadPool.
function	The ThreadFunction.
data	The user data, available to function as thread->data.

Remarks

The return value of function is discarded.

Definition at line 184 of file ThreadPool.c.

                                                                          {
  submit(self, function, data, true);
}

execute()

ThreadPoolWork * execute	(	ThreadPool *	self,
		ThreadFunction	function,
		ident	data
	)

Queues function, returning a handle to wait on.

Parameters

self	The ThreadPool.
function	The ThreadFunction.
data	The user data, available to function as thread->data.

Returns

The ThreadPoolWork, which MUST be passed to ThreadPool::wait.

Definition at line 192 of file ThreadPool.c.

                                                                                      {
  return submit(self, function, data, false);
}

init()

ThreadPool * init

(

ThreadPool *

self

)

Initializes this ThreadPool with one Thread per online processor.

Parameters

self	The ThreadPool.

Returns

The initialized ThreadPool, or NULL on error.

Definition at line 200 of file ThreadPool.c.

                                          {
 
#if defined(_WIN32)
  const size_t size = GetActiveProcessorCount(ALL_PROCESSOR_GROUPS);
#elif defined(_SC_NPROCESSORS_ONLN)
  const long processors = sysconf(_SC_NPROCESSORS_ONLN);
  const size_t size = processors > 0 ? (size_t) processors : 1;
#else
  const size_t size = 1;
#endif
 
  return $(self, initWithSize, size);
}

initWithSize()

ThreadPool * initWithSize	(	ThreadPool *	self,
		size_t	size
	)

Initializes this ThreadPool with the specified number of Threads.

Parameters

self	The ThreadPool.
size	The number of Threads. With 0, every function runs on the calling thread.

Returns

The initialized ThreadPool, or NULL on error.

Definition at line 290 of file ThreadPool.c.

                                                               {
 
  self = (ThreadPool *) super(Object, self, init);
  if (self) {
 
    self->condition = $(alloc(Condition), init);
    assert(self->condition);
 
    self->size = size;
 
    self->threads = $(alloc(Array), initWithCapacity, size);
    assert(self->threads);
 
    for (size_t i = 0; i < self->size; i++) {
      Thread *thread = $(alloc(Thread), initWithFunction, run, self);
      assert(thread);
 
      $(self->threads, addObject, thread);
      $(thread, start);
 
      release(thread);
    }
  }
 
  return self;
}

wait()

ident wait	(	ThreadPool *	self,
		ThreadPoolWork *	work
	)

Waits for the specified ThreadPoolWork to finish, and frees it.

Parameters

self	The ThreadPool.
work	The ThreadPoolWork returned by ThreadPool::execute, or NULL.

Returns

The return value of the ThreadFunction, or NULL if work is NULL.

Remarks

If work is still in the queue, it runs on the calling thread. So a ThreadFunction MAY wait on other work of its own ThreadPool without a deadlock.

---

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

• Sources/Objectively/ThreadPool.h
• Sources/Objectively/ThreadPool.c