jpool (Job Pool)

Header: udo/jpool.h

Table of contents (click to go)

Macros

Enums

Unions

Structs

1. udo_jpool_job

2. udo_jpool_queue

3. udo_jpool_thread

4. udo_jpool

5. udo_jpool_create_info

Functions

1. udo_jpool_create()

2. udo_jpool_add_job()

3. udo_jpool_wait()

4. udo_jpool_destroy()

5. udo_jpool_sizeof()

API Documentation

udo_jpool_job (private)

Structure defining information about the job to execute.

Is used in udo_jpool_add_job() to add job a to the job

queue.

struct udo_jpool_job

void (*func)(void *arg);

void *arg;

func

Function pointer to a function for thread to execute.

arg

Argument to pass to function.

udo_jpool_queue (private)

Structure defining information about the job queue.

struct udo_jpool_queue

udo_atomic_u32 *job_free;

udo_atomic_u32 *job_count;

udo_atomic_u32 *front;

udo_atomic_u32 *rear;

void *data;

uint32_t size;

job_free

Futex used to wake threads or put them

to sleep if jobs are available.

job_count

Amount of jobs currently in the given

threads pool.

front

Byte offset to the front of the queue.

rear

Byte offset to the rear of the queue.

data

Starting address caller may store data in.

size

Byte size of queue associated with thread.

udo_jpool_thread (private)

Structure defining information used by threads.

struct udo_jpool_thread

pthread_t tid;

struct udo_jpool_queue queue;

tid

POSIX thread ID associated with thread.

queue

Structure keeping track of current jobs

a thread can execute.

udo_jpool (private)

Structure defining the udo_jpool (Udo Job Pool) context.

struct udo_jpool

struct udo_log_error_struct err;

bool free;

uint32_t queue_sz;

void *queue_data;

udo_atomic_u32 *cur_thread;

uint32_t thread_count;

struct udo_jpool_thread threads[THREADS_MAX];

err

Stores information about the error that occured

for the given context and may later be retrieved

by caller.

free

If structure allocated with calloc(3) member will be

set to true so that, we know to call free(3) when

destroying the context.

queue_sz

Byte size of queue_data.

queue_data

Shared memory buffer storing actual

addresses to jobs.

cur_thread

Current thread index whose queue will have

work placed in it.

thread_count

Amount of threads in the pool.

threads

Array of threads storing location of each

threads queue and unique ID.

---

udo_jpool_create_info

Structure passed to udo_jpool_create() used

to define size of shared memory queue and

the amount of threads to create.

struct udo_jpool_create_info

size_t size;

uint32_t count;

size

Minimum size of each threads shared

memory segment used to store a threads

queue’d data.

count

Amount of threads able to read and

write to and from the shared memory

block.

struct udo_jpool *udo_jpool_create(struct udo_jpool *jpool, const void *jpool_info);

Creates pool a threads to execute task.

Job Queue (2 threads)

Variable	Offset In Bytes	Size In Bytes	Initial Value
cur_thread (main process)	0	4	1
Job Free (thread=1)	4	4	0
Front Of Queue (thread=1)	8	4	0
Rear Of Queue (thread=1)	12	4	0
Job Free (thread=2)	16	4	0
Front Of Queue (thread=2)	20	4	0
Rear Of Queue (thread=2)	24	4	0
udo_jpool_job	28	Size of queue	0
udo_jpool_job	End of thread 1 queue	Size of queue	0

Param	Decription
jpool	May be NULL or a pointer to a struct udo_jpool. If NULL memory will be allocated and return to caller. If not NULL address passed will be used to store the newly created struct udo_jpool context.
jpool_info	Implementation uses a pointer to a struct udo_jpool_create_info.

Returns:

on success: Pointer to a struct udo_jpool

on failure: NULL

---

udo_jpool_add_job

uint32_t udo_jpool_add_job(struct udo_jpool *jpool, void (*func)(void *arg), void *arg);

Adds a job to a given thread’s job queue

to then later execute. If a given thread’s

queue is full function blocks until all

jobs in that queue are completed before

adding a new task.

Param	Decription
jpool	Pointer to a valid struct udo_jpool.
func	Pointer to function that a separate thread will execute.
arg	Pointer to a memory which will be passed as the argument to func.

Returns:

on success: 0

on failure: -1

---

udo_jpool_wait

void udo_jpool_wait(struct udo_jpool *jpool);

Blocks until all jobs in every

threads queue have been completed.

Param	Decription
jpool	Pointer to a valid struct udo_jpool.

---

udo_jpool_destroy

void udo_jpool_destroy(struct udo_jpool *jpool);

Frees any allocated memory and closes FD’s (if open) created after

udo_jpool_create() call. Function waits for all jobs in every

threads queue to execute before destroying the pool.

Param	Decription
jpool	Pointer to a valid struct udo_jpool.

---

udo_jpool_get_sizeof

int udo_jpool_get_sizeof(void);

Returns size of the internal structure. So,

if caller decides to allocate memory outside

of API interface they know the exact amount

of bytes.

Returns:

on success: sizeof(struct udo_jpool)

on failure: sizeof(struct udo_jpool)

---