Process, Thread, CPU, and Mutex Functions
v3ProcessIDSyntax#include "cosmtask.h" u64 v3ProcessID( void ); DescriptionGets the ID of the current process. Return ValuesThe ID of the current process, 0 indicates failure. ErrorsPossible causes of failure:
Exampleu64 pid; pid = v3ProcessID(); if ( pid == 0 ) { /* Error */ } v3ProcessPrioritySyntax#include "cosmtask.h" u8 v3ProcessPriority( u8 priority ); DescriptionGet 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 ValuesProcess priority (mapped to 1-255 scale) after call is completed, 0 indicates failure. ErrorsPossible causes of failure:
Exampleu8 priority; u8 new_priority; priority = v3ProcessPriority( (u8) 0 ); if ( priority < 100 ) { priority =+ 40; } new_priority = v3ProcessPriority( priority ); if ( new_priority == 0 ) { /* Error */ } v3ProcessSpawnSyntax#include "cosmtask.h" u64 v3ProcessSpawn( const ascii * command, const ascii * arguments, ... ); DescriptionSpawn 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 ValuesThe child's process ID, 0 indicates failure. ErrorsPossible causes of an failure:
Exampleu64 child; child = v3ProcessSpawn( "cat", "file.txt", NULL ); if ( v3u64Eq( pid, v3u64u32( 0 ) ) ) { v3PrintA( (ascii *) "Spawn Failed\n" ); } else { v3PrintA( (ascii *) "PID = %v\n", child ); } v3ProcessSignalSyntax#include "cosmtask.h" s32 v3ProcessSignal( u64 process_id, u32 signal ); DescriptionSends signal to process process_id. Signals:
Return ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsPossible causes of failure:
Exampleu64 pid; s32 result; pid = v3ProcessID(); result = v3ProcessSignal( pid, (u32) V3_PROCESS_SIGPING ); if ( result != V3_PASS ) { /* Target process didn't exist */ } v3ProcessEndSyntax#include "cosmtask.h" void v3ProcessEnd( int status ); DescriptionEnds the current process, and all threads. Uses status as the returning exit code. Return ValuesNone. ErrorsNone. Examplev3ProcessEnd( 1 ); v3CPUCountSyntax#include "cosmtask.h" u32 v3CPUCount( void ); DescriptionGets the number of CPU's in the system. Return ValuesNumber of CPU's, 0 indicates failure. ErrorsNone. Exampleu32 numcpus; numcpus = v3CPUCount(); if ( numcpus == 0 ) { /* Error */ } v3CPUGetSyntax#include "cosmtask.h" s32 v3CPUGet( u32 * cpu ); DescriptionGet 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 ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsPossible causes of failure:
Exampleu32 cpunum; s32 result; result = v3CPUGet( &cpunum ); if ( result != V3_PASS ) { /* Error */ } v3CPULockSyntax#include "cosmtask.h" s32 v3CPULock( u64 process_id, u32 cpu ); DescriptionLocks the process process_id, and any threads, to the CPU cpu. This function is primarily for implimenting V3_MEM_SECURE memory allocation. Return ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsPossible causes of failure:
Exampleu64 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 */ } v3CPUUnlockSyntax#include "cosmtask.h" s32 v3CPUUnlock( u64 process_id ); DescriptionUnlocks 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 ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsPossible causes of failure:
Exampleu64 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 */ } v3ThreadBeginSyntax#include "cosmtask.h" u64 v3ThreadBegin( void (*start)(void *), void * arg, u32 stack_size ); DescriptionBegin a thread using the function start with argument arg with a stack size of stack_size. Stack size not supported with all OSes. Return ValuesThe assigned thread ID, 0xFFFFFFFFFFFFFFFF (-1) indicates failure. ErrorsPossible causes of failure:
Examplevoid 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 */ } v3ThreadIDSyntax#include "cosmtask.h" s32 v3ThreadID( u64 * thread_id ); DescriptionGets the current thread ID, which is stored in thread_id by reference. Return ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsPossible causes of failure:
Examples32 result; u64 tid; result = v3ThreadID( &tid ); if ( result != V3_PASS ) { /* Error */ } v3ThreadPrioritySyntax#include "cosmtask.h" u8 v3ThreadPriority( u8 priority ); DescriptionGet 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 ValuesThread priority (mapped to 1-255 scale) after call is completed, 0 indicates failure. ErrorsPossible causes of failure:
Exampleu8 priority; u8 new_priority; priority = v3ThreadPriority( (u8) 0 ); if ( priority < 100 ) { priority =+ 40; } new_priority = v3ThreadPriority( priority ); if ( new_priority == 0 ) { /* Error */ } v3ThreadEndSyntax#include "cosmtask.h" void v3ThreadEnd( void ); DescriptionEnds the calling thread. Return ValuesNone. ErrorsNone. Examplev3ThreadEnd(); v3MutexLockSyntax#include "cosmtask.h" s32 v3MutexLock( v3_MUTEX * mutex, u32 wait ); DescriptionSet 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:
Return ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsPossible causes of failure:
Examplev3_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 ); v3MutexUnlockSyntax#include "cosmtask.h" s32 v3MutexUnlock( v3_MUTEX * mutex ); DescriptionUnset an exclusive lock. Return ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsNone. Examplev3_MUTEX lock; if ( v3MutexLock( &lock, V3_MUTEX_WAIT ) != V3_PASS ) { /* bad error */ } /* do critical work */ v3MutexUnlock( &lock ); v3MutexFreeSyntax#include "cosmtask.h" void v3MutexFree( v3_MUTEX * mutex ); DescriptionFree the mutex and related system resources. Do not call this unless you are completely done with the mutex, very bad things will happen. Return ValuesNone. ErrorsNone. Examplev3SleepSyntax#include "cosmtask.h" u32 v3Sleep( u32 millisec ); DescriptionSleep for millisec milliseconds. Return Values0 if slept for complete time, or time remaining if returned early. ErrorsNone. Exampleu32 sleeptime; u32 result; sleeptime = 2300; result = v3Sleep( sleeptime ); if ( result != 0 ) { /* Didn't finish sleeping */ } v3YieldSyntax#include "cosmtask.h" void v3Yield( void ); DescriptionYield to another thread/process that wants to run. Return ValuesNone. ErrorsNone. Examplev3Yield(); v3SignalRegisterSyntax#include "cosmtask.h" s32 v3SignalRegister( u32 signal_type, void (*handler)(int) ); DescriptionRegister 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 ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsPossible causes of failure:
Examplevoid signal_function( int arg ) { /* signal code */ v3SignalRegister( V3_PROCESS_SIGINT, signal_function ); } /* ... */ if ( v3SignalRegister( V3_PROCESS_SIGINT, signal_function ) != V3_PASS ) { /* error */ } v3SystemClockSyntax#include "cosmtask.h" s32 v3SystemClock( v3_time * local_time ); DescriptionGet 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 ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsPossible causes of failure:
Examplev3_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.
|