Task Scheduler  3d2d7233
taskSch.h
Go to the documentation of this file.
1 /*
2  * Task scheduler for uniform task processing in user space.
3  * Copyright (C) 2015 Valdemar Lindberg
4  *
5  * This program is free software: you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation, either version 3 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program. If not, see <http://www.gnu.org/licenses/>.
17  *
18  */
19 #ifndef _CORE_TASK_SCH_H_
20 #define _CORE_TASK_SCH_H_ 1
21 
53 #include <stdint.h>
54 #include <stdlib.h>
55 
56 #ifdef __cplusplus
57 #include <atomic>
58 using namespace std;
59 #else
60 #include <stdatomic.h>
61 #endif
62 
63 #ifdef __cplusplus
64 extern "C" {
65 #endif
66 
71 #ifndef TASH_SCH_EXTERN
72 #ifndef TASH_SCH_STATIC
73 #ifdef _WIN32
74 #define TASH_SCH_EXTERN __declspec(dllimport)
75 #elif defined(__GNUC__) && __GNUC__ >= 4 || __clang__
76 #define TASH_SCH_EXTERN __attribute__((visibility("default")))
77 #else
78 #define TASH_SCH_EXTERN
79 #endif
80 #else
81 #define TASH_SCH_EXTERN
82 #endif
83 #endif
84 
88 #define SCH_FLAG_NO_AFM 0x80000000 /* Disable affinity mapping one to one between core and task pools. */
89 
94 #define SCH_FLAG_INIT 0x1 /* Scheduler has been initialized. */
95 #define SCH_FLAG_RUNNING 0x2 /* Scheduler is in running mode. */
96 #define SCH_FLAG_IDLE 0x4 /* Scheduler is running, but waiting for tasks. */
97 
101 #define SCH_POOL_TERMINATE 0x1 /* Pool has been terminated. */
102 #define SCH_POOL_RUNNING 0x2 /* Pool is in running mode. */
103 #define SCH_POOL_SLEEP 0x4 /* Pool is in sleep mode. */
104 
108 #define SCH_SIGNAL_IDLE (schBaseSignal() + 0) /* */
109 #define SCH_SIGNAL_RUNNING (schBaseSignal() + 1) /* */
110 #define SCH_SIGNAL_DONE (schBaseSignal() + 2) /* */
111 #define SCH_SIGNAL_CONTINUE (schBaseSignal() + 3) /* */
112 #define SCH_SIGNAL_QUIT (schBaseSignal() + 4) /* */
113 #define SCH_SIGNAL_STOP SIGSTOP
114 
126 enum SchErrCode {
127  SCH_OK = 1, /* No error. */
128  SCH_ERROR_UNKNOWN = 0, /* Error unknown. */
129  SCH_ERROR_INVALID_ARG = -1, /* Invalid argument. */
130  SCH_ERROR_INVALID_SCH = (-2), /* Invalid scheduler object. */
131  SCH_ERROR_INVALID_STATE = (-3), /* Scheduler/Pool in bad state. */
132  SCH_ERROR_INTERNAL = (-4), /* Internal error. */
133  SCH_ERROR_POOL_FULL = (-5), /* Pool queue is full. */
134  SCH_ERROR_SIGNAL = (-6), /* Signal failed. */
135  SCH_ERROR_SYNC_OBJECT = (-7), /* Synchronization object failed. */
136  SCH_ERROR_TIMEOUT = (-8), /* Timeout. */
137  SCH_ERROR_BUSY = (-9), /* Busy error. */
138  SCH_ERROR_NOMEM = (-10), /* No Memory. */
139  SCH_ERROR_LACK_OF_RESOURCES = (-11), /* There system is lacking resources. */
140  SCH_ERROR_PERMISSION_DENIED = (-12), /* Permission denied of the operation. */
141 };
149 typedef void *(*schFunc)(void *pdata); /* */
150 
156 typedef void schSpinLock; /* Spinlock sync object. */
157 typedef void schMutex; /* Mutex (mutual exclusion) sync object. */
158 typedef void schSemaphore; /* Semaphore sync object. */
159 typedef void schRWLock; /* Read/Write lock. */
160 typedef void schConditional; /* Conditional lock. */
161 typedef void schBarrier; /* Memory Barrier. */
172 typedef void schThread; /* Thread object. */
173 typedef void schSignalSet; /* Signal set object. */
178 typedef struct sch_task_scheduler_t schTaskSch;
179 typedef struct sch_task_pool_t schTaskPool;
180 typedef struct sch_task_package_t schTaskPackage;
181 
182 typedef int (*schUserCallBack)(struct sch_task_pool_t *);
183 typedef int (*schCallback)(schTaskPackage *package);
184 
188 typedef struct sch_task_package_t {
192  atomic_uint flag; /* */
196  unsigned int index;
201  schCallback callback;
205  size_t size;
209  size_t offset;
214  void *begin;
219  void *end;
223  void *puser;
224 } schTaskPackage;
225 
256 extern TASH_SCH_EXTERN int schAllocateTaskPool(schTaskSch **pSch);
257 
272 extern TASH_SCH_EXTERN int schCreateTaskPool(schTaskSch *sch, int cores, unsigned int flag,
273  unsigned int maxPackagesPool);
274 
283 extern TASH_SCH_EXTERN int schReleaseTaskSch(schTaskSch *sch);
284 
292 extern TASH_SCH_EXTERN void schSetInitCallBack(schTaskSch *sch, schUserCallBack callBack);
293 
301 extern TASH_SCH_EXTERN void schSetDeInitCallBack(schTaskSch *sch, schUserCallBack callBack);
302 
310 extern TASH_SCH_EXTERN void schSetSchUserData(schTaskSch *sch, const void *user);
311 
319 extern TASH_SCH_EXTERN void schSetPoolUserData(schTaskSch *sch, int index, const void *user);
320 
330 extern TASH_SCH_EXTERN void *schGetPoolUserData(schTaskSch *sch, int index);
331 
340 extern TASH_SCH_EXTERN schTaskPool *schGetPool(schTaskSch *sch, int index);
341 
364 extern TASH_SCH_EXTERN int schRunTaskSch(schTaskSch *sch);
365 
374 extern TASH_SCH_EXTERN int schStopTaskSch(schTaskSch *sch, long int timeout_nanoseconds);
375 
383 extern TASH_SCH_EXTERN int schTerminateTaskSch(schTaskSch *sch); // TODO give timeout option perhaps.
384 
399 extern TASH_SCH_EXTERN int schSubmitTask(schTaskSch *sch, schTaskPackage *package, schTaskPool *pPool);
400 
409 extern TASH_SCH_EXTERN int schClearTask(schTaskSch *sch, schTaskPool *pool);
410 
418 extern TASH_SCH_EXTERN int schClearAllTask(schTaskSch *sch);
419 
427 extern TASH_SCH_EXTERN int schWaitTask(schTaskSch *sch);
428 
438 extern TASH_SCH_EXTERN int schWaitTaskWait(schTaskSch *sch, long int wait_nanoseconds);
439 
446 extern TASH_SCH_EXTERN int schPoolLock(schTaskPool *pool);
447 
454 extern TASH_SCH_EXTERN int schPoolMutexUnLock(schTaskPool *pool);
455 
476 extern TASH_SCH_EXTERN schThread *schCreateThread(int affinity, schFunc pfunc, void *userData);
477 
486 extern TASH_SCH_EXTERN int schDeleteThread(schThread *thread);
487 
497 extern TASH_SCH_EXTERN int schWaitThread(schThread *thread, void **retval);
498 
507 extern TASH_SCH_EXTERN int schSetThreadName(schThread *thread, const char *name);
508 
515 extern TASH_SCH_EXTERN schThread *schCurrentThread(void);
516 
525 extern TASH_SCH_EXTERN int schRaiseThreadSignal(schThread *thread, int signal);
526 
542 extern TASH_SCH_EXTERN schSignalSet *schCreateSignal(void);
543 
550 extern TASH_SCH_EXTERN int schDeleteSignal(schSignalSet *signal);
551 
561 extern TASH_SCH_EXTERN int schBaseSignal(void);
562 
572 extern TASH_SCH_EXTERN int schSignalWait(schSignalSet *sig);
573 
583 extern TASH_SCH_EXTERN int schSignalWaitTimeOut(schSignalSet *sig, long int nanoseconds);
584 
595 extern TASH_SCH_EXTERN int schSetSignalThreadMask(schSignalSet *set, int nr, const int *signals);
596 
604 extern TASH_SCH_EXTERN int schCreateMutex(schMutex **mutex);
605 
634 extern TASH_SCH_EXTERN int schCreateSpinLock(schSpinLock **spinlock);
635 
647 extern TASH_SCH_EXTERN int schCreateSemaphore(schSemaphore **pSemaphore);
648 
663 extern TASH_SCH_EXTERN int schCreateBarrier(schBarrier **pBarrier);
664 
673 extern TASH_SCH_EXTERN int schInitBarrier(schBarrier *pBarrier, int count);
674 
682 extern TASH_SCH_EXTERN int schDeleteBarrier(schBarrier *barrier);
683 
690 extern TASH_SCH_EXTERN int schWaitBarrier(schBarrier *barrier);
691 
699 extern TASH_SCH_EXTERN int schCreateConditional(schConditional **pCondVariable);
700 
708 extern TASH_SCH_EXTERN int schDeleteConditional(schConditional *conditional);
709 
718 extern TASH_SCH_EXTERN int schConditionalWait(schConditional *conditional, schMutex *mutex);
719 
727 extern TASH_SCH_EXTERN int schConditionalSignal(schConditional *conditional);
728 
736 extern TASH_SCH_EXTERN int schCreateRWLock(schRWLock **pRwLock);
737 
745 extern TASH_SCH_EXTERN int schDeleteRWLock(schRWLock *rwLock);
746 
754 extern TASH_SCH_EXTERN int schRWLockRead(schRWLock *rwLock);
755 
763 extern TASH_SCH_EXTERN int schRWLockWrite(schRWLock *rwLock);
764 
772 extern TASH_SCH_EXTERN int schRWLocUnLock(schRWLock *rwLock);
773 
781 extern TASH_SCH_EXTERN int schDeleteMutex(schMutex *mutex);
782 
790 extern TASH_SCH_EXTERN int schDeleteSpinLock(schSpinLock *spinlock);
791 
799 extern TASH_SCH_EXTERN int schDeleteSemaphore(schSemaphore *pSemaphore);
800 
809 extern TASH_SCH_EXTERN int schMutexLock(schMutex *mutexLock);
810 
820 extern TASH_SCH_EXTERN int schMutexTryLock(schMutex *mutex, long int timeout);
821 
829 extern TASH_SCH_EXTERN int schMutexUnLock(schMutex *mutexLock);
830 
845 extern TASH_SCH_EXTERN int schSemaphoreWait(schSemaphore *pSemaphore);
846 
856 extern TASH_SCH_EXTERN int schSemaphoreTryWait(schSemaphore *semaphore);
857 
867 extern TASH_SCH_EXTERN int schSemaphoreTimedWait(schSemaphore *pSemaphore, long int timeout);
868 
878 extern TASH_SCH_EXTERN int schSemaphorePost(schSemaphore *pSemaphore);
879 
888 extern TASH_SCH_EXTERN int schSemaphoreValue(schSemaphore *pSemaphore, int *value);
889 
897 extern TASH_SCH_EXTERN int schLockSpinLock(schSpinLock *spinlock);
898 
907 extern TASH_SCH_EXTERN int schTryLockSpinLock(schSpinLock *spinLock);
908 
916 extern TASH_SCH_EXTERN int schUnlockSpinLock(schSpinLock *spinlock);
917 
939 extern TASH_SCH_EXTERN const char *schErrorMsg(int errMsg);
940 
945 #ifdef __cplusplus
946 }
947 #endif
948 
949 #endif
schSemaphoreTimedWait
TASH_SCH_EXTERN int schSemaphoreTimedWait(schSemaphore *pSemaphore, long int timeout)
schRWLocUnLock
TASH_SCH_EXTERN int schRWLocUnLock(schRWLock *rwLock)
schSetSchUserData
TASH_SCH_EXTERN void schSetSchUserData(schTaskSch *sch, const void *user)
Assign user data associated with the scheduler object.
schCreateRWLock
TASH_SCH_EXTERN int schCreateRWLock(schRWLock **pRwLock)
schCreateMutex
TASH_SCH_EXTERN int schCreateMutex(schMutex **mutex)
sch_task_package_t::offset
size_t offset
Definition: taskSch.h:209
schCurrentThread
TASH_SCH_EXTERN schThread * schCurrentThread(void)
SchErrCode
SchErrCode
Set of valid error codes. Anything equal to one or greater is considered as a success.
Definition: taskSch.h:126
schCreateSemaphore
TASH_SCH_EXTERN int schCreateSemaphore(schSemaphore **pSemaphore)
schConditionalSignal
TASH_SCH_EXTERN int schConditionalSignal(schConditional *conditional)
schCreateThread
TASH_SCH_EXTERN schThread * schCreateThread(int affinity, schFunc pfunc, void *userData)
Create new thread object with a custom callback entrypoint.
schPoolLock
TASH_SCH_EXTERN int schPoolLock(schTaskPool *pool)
schTryLockSpinLock
TASH_SCH_EXTERN int schTryLockSpinLock(schSpinLock *spinLock)
schRWLockWrite
TASH_SCH_EXTERN int schRWLockWrite(schRWLock *rwLock)
schErrorMsg
const TASH_SCH_EXTERN char * schErrorMsg(int errMsg)
schSetInitCallBack
TASH_SCH_EXTERN void schSetInitCallBack(schTaskSch *sch, schUserCallBack callBack)
Set initialization callback that will be invoked when the scheduler starts.
schCreateSpinLock
TASH_SCH_EXTERN int schCreateSpinLock(schSpinLock **spinlock)
Creates a spinlock synchronization primitive object.
sch_task_package_t::begin
void * begin
Definition: taskSch.h:214
schDeleteSpinLock
TASH_SCH_EXTERN int schDeleteSpinLock(schSpinLock *spinlock)
Release spinlock resources.
schSemaphoreWait
TASH_SCH_EXTERN int schSemaphoreWait(schSemaphore *pSemaphore)
Wait for semaphore to be unlocked.
schBaseSignal
TASH_SCH_EXTERN int schBaseSignal(void)
schGetPoolUserData
TASH_SCH_EXTERN void * schGetPoolUserData(schTaskSch *sch, int index)
Get pool user data.
schConditionalWait
TASH_SCH_EXTERN int schConditionalWait(schConditional *conditional, schMutex *mutex)
sch_task_package_t::end
void * end
Definition: taskSch.h:219
schSemaphorePost
TASH_SCH_EXTERN int schSemaphorePost(schSemaphore *pSemaphore)
schSetDeInitCallBack
TASH_SCH_EXTERN void schSetDeInitCallBack(schTaskSch *sch, schUserCallBack callBack)
Set user deinitialize callback that will be invoked when the scheduler gets terminated.
schReleaseTaskSch
TASH_SCH_EXTERN int schReleaseTaskSch(schTaskSch *sch)
Release all resources associated with the scheduler object.
schRaiseThreadSignal
TASH_SCH_EXTERN int schRaiseThreadSignal(schThread *thread, int signal)
schLockSpinLock
TASH_SCH_EXTERN int schLockSpinLock(schSpinLock *spinlock)
schStopTaskSch
TASH_SCH_EXTERN int schStopTaskSch(schTaskSch *sch, long int timeout_nanoseconds)
schDeleteBarrier
TASH_SCH_EXTERN int schDeleteBarrier(schBarrier *barrier)
schSetPoolUserData
TASH_SCH_EXTERN void schSetPoolUserData(schTaskSch *sch, int index, const void *user)
Assign user data associated with the scheduler objects pools.
schSignalWait
TASH_SCH_EXTERN int schSignalWait(schSignalSet *sig)
Wait in till signal has been issued.
TASH_SCH_EXTERN
#define TASH_SCH_EXTERN
Definition: taskSch.h:78
schSemaphoreTryWait
TASH_SCH_EXTERN int schSemaphoreTryWait(schSemaphore *semaphore)
schCreateConditional
TASH_SCH_EXTERN int schCreateConditional(schConditional **pCondVariable)
schDeleteThread
TASH_SCH_EXTERN int schDeleteThread(schThread *thread)
Delete thread This will cause the system to release the thread resources.
schAllocateTaskPool
TASH_SCH_EXTERN int schAllocateTaskPool(schTaskSch **pSch)
Allocate task scheduler object. It will make sure that for any version of the library,...
schMutexTryLock
TASH_SCH_EXTERN int schMutexTryLock(schMutex *mutex, long int timeout)
Attempt to lock the mutex. If the wait time exceeds the timeout it will return with the status of tim...
schSemaphoreValue
TASH_SCH_EXTERN int schSemaphoreValue(schSemaphore *pSemaphore, int *value)
schTerminateTaskSch
TASH_SCH_EXTERN int schTerminateTaskSch(schTaskSch *sch)
schSubmitTask
TASH_SCH_EXTERN int schSubmitTask(schTaskSch *sch, schTaskPackage *package, schTaskPool *pPool)
schSignalWaitTimeOut
TASH_SCH_EXTERN int schSignalWaitTimeOut(schSignalSet *sig, long int nanoseconds)
sch_task_scheduler_t
Task scheduler main struct container.
Definition: internal_structures.h:75
schSetThreadName
TASH_SCH_EXTERN int schSetThreadName(schThread *thread, const char *name)
schDeleteConditional
TASH_SCH_EXTERN int schDeleteConditional(schConditional *conditional)
schSetSignalThreadMask
TASH_SCH_EXTERN int schSetSignalThreadMask(schSignalSet *set, int nr, const int *signals)
sch_task_package_t::size
size_t size
Definition: taskSch.h:205
schRunTaskSch
TASH_SCH_EXTERN int schRunTaskSch(schTaskSch *sch)
schMutexLock
TASH_SCH_EXTERN int schMutexLock(schMutex *mutexLock)
Lock mutex and wait initill it has been unlocked for the thread to use the mutex.
schMutexUnLock
TASH_SCH_EXTERN int schMutexUnLock(schMutex *mutexLock)
Unlock mutex.
sch_task_package_t
Definition: taskSch.h:188
schDeleteSignal
TASH_SCH_EXTERN int schDeleteSignal(schSignalSet *signal)
schClearAllTask
TASH_SCH_EXTERN int schClearAllTask(schTaskSch *sch)
schCreateTaskPool
TASH_SCH_EXTERN int schCreateTaskPool(schTaskSch *sch, int cores, unsigned int flag, unsigned int maxPackagesPool)
Initilize task scheduler internal data structure.
schDeleteMutex
TASH_SCH_EXTERN int schDeleteMutex(schMutex *mutex)
Release resources associated with the mutex object.
schRWLockRead
TASH_SCH_EXTERN int schRWLockRead(schRWLock *rwLock)
schCreateBarrier
TASH_SCH_EXTERN int schCreateBarrier(schBarrier **pBarrier)
Create Memory barrier.
schTaskPackage
struct sch_task_package_t schTaskPackage
Definition: taskSch.h:180
sch_task_pool_t
TaskPool.
Definition: internal_structures.h:33
schGetPool
TASH_SCH_EXTERN schTaskPool * schGetPool(schTaskSch *sch, int index)
Get scheduler pool by index.
sch_task_package_t::index
unsigned int index
Definition: taskSch.h:196
schFunc
void *(* schFunc)(void *pdata)
Definition: taskSch.h:149
sch_task_package_t::flag
atomic_uint flag
Definition: taskSch.h:192
schDeleteSemaphore
TASH_SCH_EXTERN int schDeleteSemaphore(schSemaphore *pSemaphore)
Delete semaphore.
schCreateSignal
TASH_SCH_EXTERN schSignalSet * schCreateSignal(void)
schWaitTask
TASH_SCH_EXTERN int schWaitTask(schTaskSch *sch)
schWaitBarrier
TASH_SCH_EXTERN int schWaitBarrier(schBarrier *barrier)
Wait for the barrier to finish.
sch_task_package_t::puser
void * puser
Definition: taskSch.h:223
schWaitTaskWait
TASH_SCH_EXTERN int schWaitTaskWait(schTaskSch *sch, long int wait_nanoseconds)
schClearTask
TASH_SCH_EXTERN int schClearTask(schTaskSch *sch, schTaskPool *pool)
schInitBarrier
TASH_SCH_EXTERN int schInitBarrier(schBarrier *pBarrier, int count)
schUnlockSpinLock
TASH_SCH_EXTERN int schUnlockSpinLock(schSpinLock *spinlock)
schWaitThread
TASH_SCH_EXTERN int schWaitThread(schThread *thread, void **retval)
schPoolMutexUnLock
TASH_SCH_EXTERN int schPoolMutexUnLock(schTaskPool *pool)
schDeleteRWLock
TASH_SCH_EXTERN int schDeleteRWLock(schRWLock *rwLock)