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