![[Cosm Logo]](images/cosmlogo.gif)
Process, Thread, CPU, and Mutex Functions
- v3ProcessID
- v3ProcessPriority
- v3ProcessSpawn
- v3ProcessSignal
- v3ProcessEnd
- v3CPUCount
- v3CPUGet
- v3CPULock
- v3CPUUnlock
- v3ThreadBegin
- v3ThreadID
- v3ThreadPriority
- v3ThreadEnd
- v3MutexLock
- v3MutexUnlock
- v3MutexFree
- v3Sleep
- v3Yield
- v3SignalRegister
- v3SystemClock
v3ProcessID
Syntax
#include "cosmtask.h" u64 v3ProcessID( void );
Description
Gets the ID of the current process.
Return Values
The ID of the current process, 0 indicates failure.
Errors
Possible causes of failure:
- OS does not have processes.
Example
u64 pid;
pid = v3ProcessID();
if ( pid == 0 )
{
/* Error */
}
v3ProcessPriority
Syntax
#include "cosmtask.h" u8 v3ProcessPriority( u8 priority );
Description
Get or try and set the current process priority.
If priority is 0 no change is made. Otherwise the priority is set to priority.
Priorities are mapped within the range 1-255. You cannot increase the priority above the default normal priority (255) for the OS. Not all OSs will let you return to a higher priority after you reduce it.
Return Values
Process priority (mapped to 1-255 scale) after call is completed, 0 indicates failure.
Errors
Possible causes of failure:
- OS does not support this function.
- OS does not allow return to a higher priority after being set to a low priority.
Example
u8 priority;
u8 new_priority;
priority = v3ProcessPriority( (u8) 0 );
if ( priority < 100 )
{
priority =+ 40;
}
new_priority = v3ProcessPriority( priority );
if ( new_priority == 0 )
{
/* Error */
}
v3ProcessSpawn
Syntax
#include "cosmtask.h" u64 v3ProcessSpawn( const ascii * command, const ascii * arguments, ... );
Description
Spawn a new process running command. The command must be a full path in Cosm format to the binary. All additional arguments will not be modified. The arguments MUST end with a NULL.
Return Values
The child's process ID, 0 indicates failure.
Errors
Possible causes of an failure:
- OS does not support this function.
- Invalid path.
- System out of processes, memory, etc.
Example
u64 child;
child = v3ProcessSpawn( "cat", "file.txt", NULL );
if ( v3u64Eq( pid, v3u64u32( 0 ) ) )
{
v3PrintA( (ascii *) "Spawn Failed\n" );
}
else
{
v3PrintA( (ascii *) "PID = %v\n", child );
}
v3ProcessSignal
Syntax
#include "cosmtask.h" s32 v3ProcessSignal( u64 process_id, u32 signal );
Description
Sends signal to process process_id.
Signals:
- V3_PROCESS_SIGPING
- Test for Process Existance
- V3_PROCESS_SIGINT
- Save/Checkpoint.
- V3_PROCESS_SIGTERM
- Save and terminate.
- V3_PROCESS_SIGKILL
- Terminate with extreme prejudice.
Return Values
V3_PASS on success, or V3_FAIL on failure.
Errors
Possible causes of failure:
- Unknown signal.
Example
u64 pid;
s32 result;
pid = v3ProcessID();
result = v3ProcessSignal( pid, (u32) V3_PROCESS_SIGPING );
if ( result != V3_PASS )
{
/* Target process didn't exist */
}
v3ProcessEnd
Syntax
#include "cosmtask.h" void v3ProcessEnd( int status );
Description
Ends the current process, and all threads. Uses status as the returning exit code.
Return Values
None.
Errors
None.
Example
v3ProcessEnd( 1 );
v3CPUCount
Syntax
#include "cosmtask.h" u32 v3CPUCount( void );
Description
Gets the number of CPU's in the system.
Return Values
Number of CPU's, 0 indicates failure.
Errors
None.
Example
u32 numcpus;
numcpus = v3CPUCount();
if ( numcpus == 0 )
{
/* Error */
}
v3CPUGet
Syntax
#include "cosmtask.h" s32 v3CPUGet( u32 * cpu );
Description
Get the CPU number the process is running on and set cpu. Not real meaningful unless it has been locked, but may avoid a process move if called before a v3CPULock.
Return Values
V3_PASS on success, or V3_FAIL on failure.
Errors
Possible causes of failure:
- OS does not support SMP.
Example
u32 cpunum;
s32 result;
result = v3CPUGet( &cpunum );
if ( result != V3_PASS )
{
/* Error */
}
v3CPULock
Syntax
#include "cosmtask.h" s32 v3CPULock( u64 process_id, u32 cpu );
Description
Locks the process process_id, and any threads, to the CPU cpu. This function is primarily for implimenting V3_MEM_SECURE memory allocation.
Return Values
V3_PASS on success, or V3_FAIL on failure.
Errors
Possible causes of failure:
- OS does not support SMP.
Example
u64 pid;
u32 cpunum;
s32 result;
pid = v3ProcessID();
if ( pid == 0 )
{
/* Error */
}
result = v3CPUGet( &cpunum );
if ( result != V3_PASS )
{
/* Error */
}
result = v3CPULock( pid, cpunum );
if ( result != V3_PASS )
{
/* Error */
}
v3CPUUnlock
Syntax
#include "cosmtask.h" s32 v3CPUUnlock( u64 process_id );
Description
Unlocks the process process_id from a CPU. If you are using any V3_MEM_SECURE memory, calling this function would be a very very bad idea.
Return Values
V3_PASS on success, or V3_FAIL on failure.
Errors
Possible causes of failure:
- OS does not support SMP.
Example
u64 pid;
u32 cpunum;
s32 result;
pid = v3ProcessID();
if ( pid == 0 )
{
/* Error */
}
result = v3CPUGet( &cpunum );
if ( result != V3_PASS )
{
/* Error */
}
result = v3CPULock( pid, cpunum );
if ( result != V3_PASS )
{
/* Error */
}
result = v3CPUUnlock( pid );
if ( result != V3_PASS )
{
/* Error */
}
v3ThreadBegin
Syntax
#include "cosmtask.h" u64 v3ThreadBegin( void (*start)(void *), void * arg, u32 stack_size );
Description
Begin a thread using the function start with argument arg with a stack size of stack_size.
Stack size not supported with all OSes.
Return Values
The assigned thread ID, 0xFFFFFFFFFFFFFFFF (-1) indicates failure.
Errors
Possible causes of failure:
- Cosm compiled without threads support.
- System thread limit.
- Memory limit.
Example
void thread_function( void * arg )
{
u32 * puppy;
puppy = (u32 *) arg;
/* thread code */
}
/* ... */
u64 thread_id;
u32 data;
data = 42;
thread_id = v3ThreadBegin( thread_function, (void *) &data,
4096 );
if ( _V3_EQ64( thread_id, FFFFFFFF, FFFFFFFF )
{
/* thread failed to start */
}
v3ThreadID
Syntax
#include "cosmtask.h" s32 v3ThreadID( u64 * thread_id );
Description
Gets the current thread ID, which is stored in thread_id by reference.
Return Values
V3_PASS on success, or V3_FAIL on failure.
Errors
Possible causes of failure:
- Cosm compiled without threads support.
Example
s32 result;
u64 tid;
result = v3ThreadID( &tid );
if ( result != V3_PASS )
{
/* Error */
}
v3ThreadPriority
Syntax
#include "cosmtask.h" u8 v3ThreadPriority( u8 priority );
Description
Get or try and set the current thread priority.
If priority is 0 no change is made. Otherwise the priority is set to priority.
Priorities are mapped within the range 1-255. You cannot increase the priority above the default normal priority (255) for the OS.
Return Values
Thread priority (mapped to 1-255 scale) after call is completed, 0 indicates failure.
Errors
Possible causes of failure:
- OS does not support this function.
- Cosm is not compiled with threads support.
Example
u8 priority;
u8 new_priority;
priority = v3ThreadPriority( (u8) 0 );
if ( priority < 100 )
{
priority =+ 40;
}
new_priority = v3ThreadPriority( priority );
if ( new_priority == 0 )
{
/* Error */
}
v3ThreadEnd
Syntax
#include "cosmtask.h" void v3ThreadEnd( void );
Description
Ends the calling thread.
Return Values
None.
Errors
None.
Example
v3ThreadEnd();
v3MutexLock
Syntax
#include "cosmtask.h" s32 v3MutexLock( v3_MUTEX * mutex, u32 wait );
Description
Set an exclusive lock. You should never have more then one lock alive at a time per thread, as this may result in deadlock. Note that if you create a mutex you MUST free it eventually with v3MutexFree.
Wait Modes:
- V3_MUTEX_WAIT
- Do not return until the lock is available.
- V3_MUTEX_NOWAIT
- Return even if the lock was unavailable.
Return Values
V3_PASS on success, or V3_FAIL on failure.
Errors
Possible causes of failure:
- wait is invalid.
Example
v3_MUTEX lock;
if ( v3MutexLock( &lock, V3_MUTEX_WAIT ) != V3_PASS )
{
/* bad error */
}
/* do critical work */
v3MutexUnlock( &lock );
while ( v3MutexLock( &lock, V3_MUTEX_NOWAIT ) != V3_PASS )
{
/* mutex was already locked, do something */
}
/* do critical work */
v3MutexUnlock( &lock );
v3MutexUnlock
Syntax
#include "cosmtask.h" s32 v3MutexUnlock( v3_MUTEX * mutex );
Description
Unset an exclusive lock.
Return Values
V3_PASS on success, or V3_FAIL on failure.
Errors
None.
Example
v3_MUTEX lock;
if ( v3MutexLock( &lock, V3_MUTEX_WAIT ) != V3_PASS )
{
/* bad error */
}
/* do critical work */
v3MutexUnlock( &lock );
v3MutexFree
Syntax
#include "cosmtask.h" void v3MutexFree( v3_MUTEX * mutex );
Description
Free the mutex and related system resources. Do not call this unless you are completely done with the mutex, very bad things will happen.
Return Values
None.
Errors
None.
Example
v3Sleep
Syntax
#include "cosmtask.h" u32 v3Sleep( u32 millisec );
Description
Sleep for millisec milliseconds.
Return Values
0 if slept for complete time, or time remaining if returned early.
Errors
None.
Example
u32 sleeptime;
u32 result;
sleeptime = 2300;
result = v3Sleep( sleeptime );
if ( result != 0 )
{
/* Didn't finish sleeping */
}
v3Yield
Syntax
#include "cosmtask.h" void v3Yield( void );
Description
Yield to another thread/process that wants to run.
Return Values
None.
Errors
None.
Example
v3Yield();
v3SignalRegister
Syntax
#include "cosmtask.h" s32 v3SignalRegister( u32 signal_type, void (*handler)(int) );
Description
Register handler as the handler for signal_type. signal_type must be either V3_PROCESS_SIGINT or V3_PROCESS_SIGTERM. See v3ProcessSignal for sending signals. Once the handler is triggered the OS will reset the handler, so if you wish to reuse a signal, you must call reregister it.
Return Values
V3_PASS on success, or V3_FAIL on failure.
Errors
Possible causes of failure:
- Unknown signal.
- OS does not support this function.
Example
void signal_function( int arg )
{
/* signal code */
v3SignalRegister( V3_PROCESS_SIGINT, signal_function );
}
/* ... */
if ( v3SignalRegister( V3_PROCESS_SIGINT, signal_function )
!= V3_PASS )
{
/* error */
}
v3SystemClock
Syntax
#include "cosmtask.h" s32 v3SystemClock( v3_time * local_time );
Description
Get the time from the system clock and set local_time. v3_time is a signed number (s128) of seconds in 64b.64b fixed point format based on the time 0 = 00:00:00 UTC, Jan 1, 2000 AD.
Return Values
V3_PASS on success, or V3_FAIL on failure.
Errors
Possible causes of failure:
- System has no hardware clock.
Example
v3_time clock;
if ( v3SystemClock( &clock ) != V3_PASS )
{
/* temporal rift */
}
© Copyright Mithral Communications & Design, Inc. 1999.
All rights reserved.
Mithral(tm) and Cosm(tm) are trademarks of
Mithral Communications & Design, Inc.
Document last modified: