Contents

• Copyright disclaimer
• C Interface reference
• C++ Interface reference

All the files marked with the above copyright fall either under LGPL (Library General Public License) or under GPL (General Public License) as stated at the beginning of each file, with the following exception, that ALL the people in the THANKS file must receive credit. The example*.* files are FREEWARE. You can do whatever you want with them.

All these files are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License and of the GNU Library General Public License along with this program; see the files COPYING and COPYING.LIB. If not, write to the Free Software Foundation, Inc., 675 Mass Ave., Cambridge, MA 02139, USA.

So came out this package. It is basically divided in three sections:

lwpasm.S (Capital "S"!)

The assembler stuff

lwp.c

The "C" part of the business

threads.cc

The C++ interface.

int lwp_init(int irq,int speed)

NOTE: IRQ0 doesn't work under Win 95. I haven't tested it under OS/2 or Win 3.1. I think Windows hooks it.

Example:

if(lwp_init(8,RTC128))
{
    ... do your stuff ...
} else printf("Error!\n");

int lwp_spawn(void (*proc)(void *), void * arg, int stack_size,int priority)

Example:

void proc(void *arg)
{
   printf("My proc is %s!\n", (char *) arg );
}
main()
{
   lwp_init(0,100);
   lwp_spawn(proc, "kewl", 4096,1);
   /* do some stuff...*/

}

int lwp_kill(int lwpid)

NOTE: main() can't be killed!
NOTE: Processes that return automagically kill themselves.

Returns 0 if couldn't kill thread, 1 if thread was correctly killed

int lwp_getpid(void)

Example:

void proc1()
{
    ...do stuff...
    lwp_kill(lwp_getpid());
    /* never returns */
}

void lwp_thread_disable(void)

void lwp_thread_enable(void)

Example:

  lwp_thread_disable();
  printf("foo = %d\n", foo);
  lwp_thread_enable();

void lwp_yield(void)

while(!kbhit())
{
    wait++;        /* Waste time...*/
}

while(!kbhit()) /* Locks the processor! */
{
    wait++;     /* Waste time...*/
   lwp_yield(); /* Give the other threads a chance too... */
}

void lwp_atkill(void (*proc)(void))

Example:

void exitproca(void)

{

    printf("Finished 2\n");

}

void exitprocb(void)

{

    printf("Finished 1\n");

}

void thread(void *unused)

{

    ...

    lwp_atkill(exitproca);

    lwp_atkill(exitprocb);

Output:

Finished 1

Finished 2

void lwp_sleep(unsigned int secs,unsigned short msecs)

Example:

void periodic_check(void)
{
   while(!finished)
   {
      lwp_sleep(60*15,0);    /* Wait 15 minutes */
      autosave();
   }
}

void lwp_setuserptr(void *usrdata)

void *lwp_getuserptr(void)

void lwp_wait_true(volatile int *what)

void lwp_wait_false(volatile int *what)

Example:

volatile int trigger = 0;

void triggered_task(void)
{
    lwp_wait_true(&trigger);
    ... Does what it has to do...
}

void main()
{
   lwp_spawn(triggered_task,8192);

   ...Waits for some event...

   trigger = 1;    // Here it is. From this moment, the triggered_task
                   // can proceed!
   ... Does the rest of its stuff...
}

void lwp_pulse_true(volatile int *what)

void lwp_pulse_false(volatile int *what)

void lwp_wait_semaphore(lwp_semaphore *sema)

void lwp_init_semaphore(lwp_semaphore *sema)

int lwp_release_semaphore(lwp_semaphore *sema)

Example:

lwp_semaphore sema;

int count = 0;
void thread(void)
{
    ... Does some stuff ...
    lwp_wait_semaphore(&sema);    //Wait until semaphore is free
    count++;                      // Do something...
    lwp_release_semaphore(&sema); // Make the semaphore free again.

    ... Does some other stuff ...
}

void lwp_set_priority(unsigned priority)

unsigned lwp_get_priority(void)

• class CritSect
• class MutexSemaphore/MutexSemaphoreLock
• class CountSemaphore
• template class SerializedQueue<T>
• class Gate
• class Event
• class ReadWriteSemaphore/WriteLock/ReadLock
• class Thread/Message

Class CritSect

int count=0;

void func(void)

{
 ... Some stuff...
 do {
     CritSect sect;
     count++;
 } while(0);
 ... More stuff ...
}

Classes MutexSemaphore / MutexSemaphoreLock

Example

MutexSemaphore sema; // Initializes itself on its own.
void func(void)
{
 do {
   MutexSemaphoreLock lock(sema);
   ... Do your private stuff with the semaphore locked...
 } while(0);
 ... Now semaphore is automagically unlocked...
}

MutexSemaphore sema;
void func(void)
{
 do {
   MutexSemaphoreLock lock(sema);
   do_stuff();
 } while(0);      // The semaphore is unlocked only here, as one 
                  //might expect.
}

void do_stuff(void)
{
   MutexSemaphoreLock lock(sema); // The semaphore was already locked!
   ... Whatever this function does...
}                                 // And is NOT unlocked here!

class CountSemaphore

CountSemaphore monsters_sema;
void monster(void *unused)
{
   monsters_sema.Wait();  // Wait for ok from theGame()

   ...Boo! Eat the player! ...
}

main()
{

... Multithreading is initialised, all your stuff is done...

   if(level == 1 )     // Spawn 10 (sleeping) monsters.
   {
       for(int i = 0; i < 10; i++) lwp_spawn(monster,(void*)0,8192,1);
   } else              // Spawn 20 (sleeping) monsters.
   {
       for(int i = 0; i < 20; i++) lwp_spawn(monster,(void*)0,8192,1);
   };

   ... At a certain point, you call the main game loop ...

   theGame();
}

void theGame(void)
{
    ... You want to materialize a certain number of monsters ...
    if(level == 1)
    {
       monsters_sema.Clear();  // Let one process pass on...
    } else
    {
       monsters_sema.Clear(2); // Wake up two processes!
    };
}

Class SerializedQueue<T>

class Gate

Example: (see the file test/example6.cc too)

If in that game you wanted to introduce a "pause" key, you could write:

Gate pauseGate(1); // Initialize it to be open!

main()
{

 ... Some stuff ...
 if( pause_key_pressed() )
 {
     pauseGate.Close(); // Stop all the other game threads!

     while(!kbhit()) lwp_yield(); // Wait for another key pressure...

     pauseGate.Open(); // Re-open the gate
 }

 ... Rest of the game ...
}

void game(void)
{
   ... There is some code...
   while(!game_over)
   {
      pauseGate.Wait(); // Wait for the gate to be opened, or pass on if it
                        // is already open.
      ... Play ...
   };
}

void monster(void)
{
   ... There is some code to draw the monster ...
   while(alive)
   {
      pauseGate.Wait(); // Wait for the gate to be opened, or pass on
                        // if it is already open.
      ... Move the monster ...
   };
   ... Make the monster disappear ...
}

Class Event

See the file test/example9.cc for an example of using the Event class.
 

Classes ReadWriteSemaphore/ReadLock/Writelock

Interface to this class is very simple, as the example shows:

Example (see the file test/example5.cc)

ReadWriteSemaphore sema;

int ToBeProtected;
void thread1(void)
{
  int tmp;
  ... Some stuff ...
  do { 
     ReadLock lock(sema);
     tmp = ToBeProtected;
  } while(0);
  ... Rest of the stuff ...
}
void thread2(void)
{
  int tmp;
  ... Some stuff ...
  do { 
     WriteLock lock(sema);
     ToBeProtected++;
  } while(0);
  ... Rest of the stuff ...
}

Class Thread

class MyThread : public Thread
{
public:
   MyThread(unsigned int stacksize) : Thread(stacksize) { };
   virtual void prepare(void); // Starts as soon as the thread is created
   virtual void execute(void); // Starts when the thread is "start()"ed
   virtual void cleanup(void); // Starts when execute() returns
}

• The prepare() function you provide is called as soon as the Thread-derived object is created, i.e. at the end of the constructor.
• The execute() function is called ONLY when another thread calls the "start" member function. This allows for synchronization in thread starting.
• The cleanup() function instead is called when the "execute()" function has returned; i.e., when the "job" has been performed, and you might need to "clean up" the situation.

But Thread object don't provide only these services: their most important role is allowing threads to exchange messages. A message is simply a pointer to void, that you "post()" to another thread. The Thread objects provides two methods to do it:

void postMessage(void *) and
static void postMessage(void *,Thread& dest).

The first can be used so:

    myThread.postMessage("Hello!");

    Thread::postMessage("Hello",myThread);

Receiving a message is very simple too, but one thing must be understood: you send just void*, but you receive Message objects, containing another important datum, i.e. the sender. Thus, to receive that message, and print all the relevant data, you should write:

void myThread::execute(void)
{
 do {
    Message theMessage = getMessage(); // Inside execute(), you have
                                       // access to member functions!
    if(theMessage.Contents() == 0) break;

    printf("Message is: %s from thread with pid(%i)\n",
           (char*)(theMessage.Contents()),
           theMessage.Source()->getPid());

 } while(1);
}

1. The getMessage() method waits for a message to be sent, THEN returns it. Pay attention to deadlocks!
2. Messages arrive in the order in which they were posted. I was very careful about it: they are put in a queue (obviously, in a serialized queue).
3. In fact, you are not limited at all to sending char*! You can send ANY pointer with the postMessage()/getMessage() method.
4. When you perform a getMessage(), the message is removed from the queue. If you want to check how many message are waiting to be processed, use the waitingMessages() method, or the noMessages() to check whether the messages queue is empty.

   void InitLwp(speed)

   void DoneLwp(void)

Mainly, PAY ATTENTION TO WHAT YOU DO! I have tried to shield the thing up as much as I could, isolating operator new, operator delete, malloc, realloc, free, calloc, cfree, but anyhow PAY ATTENTION to non-reentrant routines, and remember THERE ARE MANY!.

Anyhow, if you have suggestions, ideas, comments, or just want to say hello, don't hesitate to mail me.

Standard Disclaimer