# KIO's Thread Dispatcher - Documentation

## Semaphors

### Overview

Semaphors are a kind of traffic light, by which you can control the access to limited resources. The first thread which requests a semaphor gets it and blocks it; threads which subsequently request this semaphor are suspended until the semaphor is released, most likely by the thread which blocked it. This way you can limit concurrent access to a function which is not reentrant-safe to one thread at a time.

Semaphors can count: You can request or release them multiple times, e.g. to control access to a module which can handle a certain limited amount of threads at a time, not just one.

The request for a semaphor can be combined with a timeout. After having requested it with timeout, you must always verify that you've actually got the semaphor.

If a thread requests a semaphor which was blocked by itself, the thread is not blocked, only the request counter is incremented accordingly. This makes encapsulation of modules using a single semaphor easier.

If a semaphor is blocked by a low-prio thread and a high-prio thread tries to request that semaphor, the priority of the blocking thread is raised to the priority of the requester until it releases the semaphor. This way a low-prio thread doesn't block a high-prio thread for an unacceptable time.

### Class Sema

    class Sema
    {
    public:     Sema        ( );
                ~Sema       ( );
                Sema        ( const Sema& );
                operator=   ( const Sema& );

        bool    IsFree      ( ) const;
        bool    IsBlocked   ( ) const;
        bool    IsAvailable ( ) const;
        bool    IsNotAvailable()const;
        bool    IsMine      ( ) const;
        bool    IsNotMine   ( ) const;
        bool    IsWaiting   ( ) const;
        Tid     Owner       ( ) const;

        void    Clear       ( );
        void    Request     ( int n=1 );
        void    Release     ( int n=1 );
        void    Request     ( int n, long timeout );
    };

### Create a Semaphor

### Destroy a Semaphor

### void Clear()

### void Request()

### void Release()

### Query State of Semaphor

### Find thread blocking a semaphor

### Find semaphors blocked by a thread

void Clear ( Sema& s ) clear semaphore This call clears a semaphor and releases all threads which may be waiting for it. Requests without timeout will retry to get the semaphor, Requests with timeout will return without locking it. The next Request() for this semaphor will lock it. void Request ( Sema& s, int n=1 ) request semaphore Request a semaphor without timeout. Semaphores can count, so you can request it a precise number of times. This request blocks your thread, if the semaphore is occupied by someone else until it is released. If the semaphor is free, it get's locked by your thread and it returns. If you already own this semaphore, your requests are just counted and the procedure returns. You can not lock yourself this way! This comes in handy if you protect a whole module by a semaphor. You have a lot of methods which can be called from outside, each surrounded by a Request() and Release() to a dedicated semaphor. Because you cannot self-lock, one protected method can call another protected method without trouble. This function only returns when it has sucessfully requested and locked a semaphor. If your thread gets blocked, the priority of the blocking thread is boosted to your own, if it was lower. This ensures that a low priority thread cannot block important threads for unacceptable durations this way. void Request ( Sema& s, int n,long duration ) request semaphor with timeout Basically the same as above, except that you have provided a timeout. This function returns if one of the following occurs: - the semaphor was successfully requested and locked - the timeout expired - your thread is resumed from another thread void Release ( Sema& s, int n=1 ) release semaphor After you are done with your precious task, you must calls to Release() to balance your Request()s. As with Request() Release() can take a number for how often to release the semaphor. In most applications you will request and release it just once, each. If there are threads waiting they are all resumed. They will retry to request the semaphor and the highest priority thread will get it first.