[Cosm Logo]

Process, Thread, CPU, and Mutex Functions

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();

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"
s32 v3ProcessSpawn( u64 * process_id, 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. process_id is set to the process ID of the swawned process. The arguments MUST end with a NULL.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of an failure:

  • OS does not support this function.
  • Invalid path.
  • System out of processes, memory, etc.

Example

 
  u64 child;

  if ( v3ProcessSpawn( &child, "cat", "file.txt",
    "file2.txt", NULL ) != V3_PASS )
  {
    v3PrintA( (ascii *) "Spawn Failed\n" );
  }
  else
  {
    v3PrintA( (ascii *) "Child 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_SIGNAL_PING
Test for Process Existance
V3_SIGNAL_INT
Save/Checkpoint.
V3_SIGNAL_TERM
Save and terminate.
V3_SIGNAL_KILL
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_SIGNAL_PING );
  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. All programs should always exit this way.

Return Values

None.

Errors

None.

Example

 
  v3ProcessEnd( 1 );

v3CPUCount

Syntax

 
#include "cosmtask.h"
s32 v3CPUCount( u32 * count );

Description

Sets count to the number of CPU's in the system. count will always be set to 1 or more even on failure, which indicates the system was not able to detect additional CPUs.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of failure:

  • OS does not support SMP.
  • OS does not provide a system call for the number of CPUs.

Example

 
  u32 num_cpus;

  if ( v3CPUCount( &num_cpus ) == V3_FAIL )
  {
    /* error, but num_cpus is 1 */
  }

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"
s32 v3ThreadBegin( u64 * thread_id, 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. thread_id is set to the thread ID of the new thread.

Stack size not supported with all OSes.

Return Values

V3_PASS on success, or V3_FAIL on 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;
  if ( v3ThreadBegin( &thread_id, thread_function,
    (void *) &data, 4096 ) != V3_PASS )
  {
    /* thread failed to start */
  }

v3ThreadID

Syntax

 
#include "cosmtask.h"
u64 v3ThreadID( void );

Description

Gets the current thread ID.

Return Values

The current thread ID, 0 indicates failure.

Errors

Possible causes of failure:

  • Cosm compiled without threads support.

Example

 
  u64 thread_id;

  thread_id = v3ThreadID();

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;

  v3MemSet( &lock, v3u64u32( sizeof( v3_MUTEX ) ), 0 );

  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 );

  v3MutexFree( &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;

  v3MemSet( &lock, v3u64u32( sizeof( v3_MUTEX ) ), 0 );

  if ( v3MutexLock( &lock, V3_MUTEX_WAIT ) != V3_PASS )
  {
    /* bad error */
  }

  /* do critical work */

  v3MutexUnlock( &lock );

  v3MutexFree( &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

 
  v3_MUTEX lock;

  v3MemSet( &lock, v3u64u32( sizeof( v3_MUTEX ) ), 0 );

  if ( v3MutexLock( &lock, V3_MUTEX_WAIT ) != V3_PASS )
  {
    /* bad error */
  }

  /* do critical work */

  v3MutexUnlock( &lock );

  v3MutexFree( &lock );

v3Sleep

Syntax

 
#include "cosmtask.h"
void v3Sleep( u32 millisec );

Description

Sleep for millisec milliseconds.

Return Values

None.

Errors

None.

Example

 
  /* sleep for 10 seconds */
  v3Sleep( 10000 );

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_SIGNAL_INT or V3_SIGNAL_TERM. 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 reregister it in the handler. Inside of your signal handler you must be very careful as any thread may end up running the handler at any time. Make your handler as short as possible.

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_SIGNAL_INT, signal_function );
    /* set a flag or other handler actions */
  }

  /* ... */

  if ( v3SignalRegister( V3_SIGNAL_INT, 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. 1995-2003. All rights reserved. Mithral® and Cosm® are trademarks of Mithral Communications & Design Inc.
Document last modified: May 22, 2003