[Cosm Logo]

Process, Thread, CPU, and Mutex Functions

CosmProcessID

Syntax

 
#include "cosm/os_task.h"
u64 CosmProcessID( 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 = CosmProcessID();

CosmProcessPriority

Syntax

 
#include "cosm/os_task.h"
u8 CosmProcessPriority( 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 = CosmProcessPriority( (u8) 0 );
  if ( priority < 100 )
  {
    priority =+ 40;
  }

  new_priority = CosmProcessPriority( priority );
  if ( new_priority == 0 )
  {
    /* Error */
  }

CosmProcessSpawn

Syntax

 
#include "cosm/os_task.h"
s32 CosmProcessSpawn( 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

COSM_PASS on success, or COSM_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 ( CosmProcessSpawn( &child, "cat", "file.txt",
    "file2.txt", NULL ) != COSM_PASS )
  {
    CosmPrint( "Spawn Failed\n" );
  }
  else
  {
    CosmPrint( "Child PID = %v\n", child );
  }

CosmProcessEnd

Syntax

 
#include "cosm/os_task.h"
void CosmProcessEnd( int status );

Description

Ends the current process, and all threads. Uses status as the returning exit code. Programs must always exit this way, or system resources may not be freed on certain operating systems.

Return Values

None.

Errors

None.

Example

 
  CosmProcessEnd( 1 );

CosmCPUCount

Syntax

 
#include "cosm/os_task.h"
s32 CosmCPUCount( u32 * count );

Description

Sets count to the number of CPUs in the system. Note that count will be set to 1 on failure since machines with zero CPUs do not exist.

Return Values

COSM_PASS on success, or COSM_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 ( CosmCPUCount( &num_cpus ) == COSM_FAIL )
  {
    /* error, but num_cpus is 1 */
  }

CosmCPULock

Syntax

 
#include "cosm/os_task.h"
s32 CosmCPULock( u64 process_id, u32 cpu );

Description

Locks the process process_id, and any threads, to the CPU cpu. This function can be used for a large variety of performance and security reasons.

Return Values

COSM_PASS on success, or COSM_FAIL on failure.

Errors

Possible causes of failure:

  • OS does not support SMP.

Example

 
  u64 pid;
  u32 cpunum;
  s32 result;

  pid = CosmProcessID();
  if ( pid == 0 )
  {
    /* Error */
  }

  result = CosmCPUGet( &cpunum );
  if ( result != COSM_PASS )
  {
    /* Error */
  }

  result = CosmCPULock( pid, cpunum );
  if ( result != COSM_PASS )
  {
    /* Error */
  }

CosmCPUUnlock

Syntax

 
#include "cosm/os_task.h"
s32 CosmCPUUnlock( u64 process_id );

Description

Unlocks the process process_id and its threads from a CPU. If you are using any secure memory, calling this function would be a bad idea.

Return Values

COSM_PASS on success, or COSM_FAIL on failure.

Errors

Possible causes of failure:

  • OS does not support SMP.

Example

 
  u64 pid;
  u32 cpunum;
  s32 result;

  pid = CosmProcessID();
  if ( pid == 0 )
  {
    /* Error */
  }

  result = CosmCPUGet( &cpunum );
  if ( result != COSM_PASS )
  {
    /* Error */
  }

  result = CosmCPULock( pid, cpunum );
  if ( result != COSM_PASS )
  {
    /* Error */
  }

  result = CosmCPUUnlock( pid );
  if ( result != COSM_PASS )
  {
    /* Error */
  }

CosmThreadBegin

Syntax

 
#include "cosm/os_task.h"
s32 CosmThreadBegin( 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

COSM_PASS on success, or COSM_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 ( CosmThreadBegin( &thread_id, thread_function,
    (void *) &data, 4096 ) != COSM_PASS )
  {
    /* thread failed to start */
  }

CosmThreadID

Syntax

 
#include "cosm/os_task.h"
u64 CosmThreadID( 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 = CosmThreadID();

CosmThreadPriority

Syntax

 
#include "cosm/os_task.h"
u8 CosmThreadPriority( 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 = CosmThreadPriority( (u8) 0 );
  if ( priority < 100 )
  {
    priority =+ 40;
  }

  new_priority = CosmThreadPriority( priority );
  if ( new_priority == 0 )
  {
    /* Error */
  }

CosmThreadEnd

Syntax

 
#include "cosm/os_task.h"
void CosmThreadEnd( void );

Description

Ends the calling thread.

Return Values

None.

Errors

None.

Example

 
  CosmThreadEnd();

CosmMutexLock

Syntax

 
#include "cosm/os_task.h"
s32 CosmMutexLock( cosm_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 CosmMutexFree.

Wait Modes:

COSM_MUTEX_WAIT
Do not return until the lock is available.
COSM_MUTEX_NOWAIT
Return even if the lock was unavailable.

Return Values

COSM_PASS on success, or COSM_FAIL on failure.

Errors

Possible causes of failure:

  • wait is invalid.

Example

 
  cosm_MUTEX lock;

  CosmMemSet( &lock, sizeof( cosm_MUTEX ), 0 );

  if ( CosmMutexLock( &lock, COSM_MUTEX_WAIT ) != COSM_PASS )
  {
    /* bad error */
  }

  /* do critical work */

  CosmMutexUnlock( &lock );

  while ( CosmMutexLock( &lock, COSM_MUTEX_NOWAIT ) != COSM_PASS )
  {
    /* mutex was already locked, do something */
  }

  /* do critical work */

  CosmMutexUnlock( &lock );

  CosmMutexFree( &lock );

CosmMutexUnlock

Syntax

 
#include "cosm/os_task.h"
s32 CosmMutexUnlock( cosm_MUTEX * mutex );

Description

Unset an exclusive lock.

Return Values

COSM_PASS on success, or COSM_FAIL on failure.

Errors

None.

Example

 
  cosm_MUTEX lock;

  CosmMemSet( &lock, sizeof( cosm_MUTEX ), 0 );

  if ( CosmMutexLock( &lock, COSM_MUTEX_WAIT ) != COSM_PASS )
  {
    /* bad error */
  }

  /* do critical work */

  CosmMutexUnlock( &lock );

  CosmMutexFree( &lock );

CosmMutexFree

Syntax

 
#include "cosm/os_task.h"
void CosmMutexFree( cosm_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

 
  cosm_MUTEX lock;

  CosmMemSet( &lock, sizeof( cosm_MUTEX ), 0 );

  if ( CosmMutexLock( &lock, COSM_MUTEX_WAIT ) != COSM_PASS )
  {
    /* bad error */
  }

  /* do critical work */

  CosmMutexUnlock( &lock );

  CosmMutexFree( &lock );

CosmSleep

Syntax

 
#include "cosm/os_task.h"
void CosmSleep( u32 millisec );

Description

Sleep for millisec milliseconds.

Return Values

None.

Errors

None.

Example

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

CosmYield

Syntax

 
#include "cosm/os_task.h"
void CosmYield( void );

Description

Yield to another thread/process that wants to run.

Return Values

None.

Errors

None.

Example

 
  CosmYield();

CosmSignal

Syntax

 
#include "cosm/os_task.h"
s32 CosmSignal( u64 process_id, u32 signal );

Description

Sends signal to process process_id.

Signals:

COSM_SIGNAL_PING
Test for Process Existance
COSM_SIGNAL_INT
Save/Checkpoint.
COSM_SIGNAL_TERM
Save and terminate.
COSM_SIGNAL_KILL
Terminate with extreme prejudice.

Return Values

COSM_PASS on success, or COSM_FAIL on failure.

Errors

Possible causes of failure:

  • Unknown signal.

Example

 
  u64 pid;
  s32 result;

  pid = CosmProcessID();

  result = CosmSignal( pid, COSM_SIGNAL_PING );
  if ( result != COSM_PASS )
  {
    /* Target process didn't exist */
  }

CosmSignalRegister

Syntax

 
#include "cosm/os_task.h"
s32 CosmSignalRegister( u32 signal_type, void (*handler)(int) );

Description

Register handler as the handler for signal_type. signal_type must be either COSM_SIGNAL_INT or COSM_SIGNAL_TERM. See CosmSignal 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

COSM_PASS on success, or COSM_FAIL on failure.

Errors

Possible causes of failure:

  • Unknown signal.
  • OS does not support this function.

Example

 
  void signal_function( int arg )
  {
    /* signal code */
    CosmSignalRegister( COSM_SIGNAL_INT, signal_function );
    /* set a flag or other handler actions */
  }

  /* ... */

  if ( CosmSignalRegister( COSM_SIGNAL_INT, signal_function )
    != COSM_PASS )
  {
    /* error */
  }

CosmSystemClock

Syntax

 
#include "cosm/os_task.h"
s32 CosmSystemClock( cosmtime * clock );

Description

Sets the value of clock from the system clock. cosmtime 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

COSM_PASS on success, or COSM_FAIL on failure.

Errors

Possible causes of failure:

  • System has no hardware clock.

Example

 
  cosmtime clock;

  if ( CosmSystemClock( &clock ) != COSM_PASS )
  {
    /* temporal rift */
  }

© Copyright Mithral Communications & Design Inc. 1995-2024. All rights reserved. Mithral® and Cosm® are trademarks of Mithral Communications & Design Inc.
Document last modified: Jun 01, 2012