Appendix A. Virtual System API

This module is a set of virtual "system calls". This is an ANSI-C code, but the ANSI standard C library does not support some useful features of modern OSes (e.g. no multi-thread support is present). To make modules free of system dependent system calls (i.e. to make the project more portable) module "Virtual System API" is used in any other module when it must use non-ANSI features. The following structures are present:

To use shared data the following structures were prepared: semaphore_struct and ssp, defined as

	typedef struct semaphore_struct *ssp;

These structures are used to manage a "semaphore structure". The variable of the type ssp is returned by function creating this structure and used later to protect some shared data. There is no need to introduce the field of the structure. In Windows environment they are implemented using Mutexes and Events.

To manage multiple threads the following structures are used: thread_id and tidp, defined as:

	typedef struct thread_id *tidp;

The following API has been prepared:

• prepare_ss Allocates a new semaphore structure object.

  ssp prepare_ss(void);

  Prepares a new semaphore structure, returns pointer to newly allocated structure or NULL if no data can be allocated.

• lockit Locks a semaphore.

  void lockit(ssp ss_object);

  Locks the semaphore that is pointed by ss_object. If someone has already locked the semaphore, this functions blocks. No processes using lock/unlock pair can come into critical section.

• unlockit Unlocks a semaphore.

  void unlockit(ssp ss_object);

  Unlocks the semaphore that pointed by the ss_object semaphore object. If there is one blocked thread on this semaphore, it is unblocked and gets into the critical section. If multiple threads are blocked on the semaphore, one of them is unblocked.

• checklock Checks whether a semaphore is locked.

  void checklock(ssp ss_object);

  Returns 1 if semaphore is already locked or 0 if not.

• wait_for_resource Starts waiting for a "new resource".

  void wait_for_resource(ssp ss_object);

  Blocks waiting for an event (called here a "new resource"). This function must be called when inside critical section (lockit called before) because it unlocks this semaphore to allow the other thread go inside critical section to call new_resource (described below).

• new_resource Signals a "new resource".

  void new_resource(ssp ss_object);

  If any other thread is waiting for a "new resource" (it called wait_for_resource function) this functions unblocks the waiting thread. Otherwise it does nothing.

• make_thread Creates a new thread.

  tidp make_thread(fun_ptr function, void *parameter);

  Creates new thread with function function and parameters passed to it in param. Returns pointer to this thread or NULL if it cannot be created.

• kill_thread Kills (terminates) a running thread.

  tidp kill_thread(tidp thread_ID);

  This function is called from the outside of the thread. This functions should be used with consciousness what it does in a given OS. It must not be used with threads having critical sections.

• exit_thread Terminates a thread.

  void exit_thread(int retval);

  This function is called from the inside of the thread, which wants to terminate itself (exit). retval is a return value.

• fallasleep Portable sleep().

  void fallasleep(int seconds);

  Just falls asleep for seconds of seconds.

• put_message Prints a message.

  void put_message(const char *seconds ...);

  Prints the message s. This function works like printf so multiple arguments are possible. In this, console version it calls printf.

• put_debug_message Prints a message when debugging.

  void put_debug_message(const char *seconds ...);

  Prints message only when _DEBUG is defined.