IlsThread

Category

Thread utility class - API FOR ADVANCED USERS

Inheritance Path

IlsMTBase
➥ IlsThread

Description

A thread object is used to create a new thread of execution. There is no thread object associated with the main thread. Thread classes are special classes in that the life span of the thread can outlive the life of the thread object.

Libraries

Header File

#include <ilserver/ilthread.h>

Synopsis

class IlsThread: public IlsMTBase

{

public:

IlsThread(IlsThreadStartFunc, IlsAny = 0, int = 0);

virtual ~IlsThread();

IlsBoolean wasCreated() const;

IlsBoolean isAlive() const;

const IlsThreadId getIdentifier() const;

static const IlsThreadId GetCurrentIdentifier();

static void Join(IlsThread*);

void join();

static void Yield();

static void ExitCurrentThread();

void addTerminatedCallback(IlsThreadTerminateFunc, IlsAny = 0);

void removeTerminatedCallback(IlsThreadTerminateFunc, IlsAny=0);

friend ostream& operator<<(ostream&, const IlsThread&);

static IlsBoolean Mtsafe();

};

Constructor

IlsThread(IlsThreadStartFunc, IlsAny = 0, int = 0);

The constructor of a thread takes the start procedure as its first argument. This procedure is the one that is run when the thread starts. The start function for a thread takes a single parameter as its argument, which is the second argument to the constructor. This argument will normally be cast to the correct type within the start function. The third optional argument of the thread constructor is the stack size for the thread being created. We recommend that you supply the stack size. If you do not supply it, a platform-dependent value will be used. It should not be assumed that stack overflow in a thread will be detected by the underlying operating system.


Note: Creating a thread does not mean that the thread will be run immediately. The execution of a thread depends on the platform on which the program is running.

Destructor

virtual ~IlsThread();

Destroying a thread object does not destroy the thread. In the same way, a thread may exit, and hence no longer be valid even though the thread object still exists. The member function isAlive can be used to check whether the system thread is still running.

Member Functions

IlsBoolean wasCreated() const;

This member function tests the status of the thread. It returns IlsFalse if the thread was not created successfully.

IlsBoolean isAlive() const;

This member function tests the status of the thread. It returns IlsTrue if the thread was created successfully and has not yet exited. This does not mean that the thread has been scheduled yet nor that the start function has been executed.

const IlsThreadId getIdentifier() const;

This member function returns an operating system-dependent value which may be the address of the thread or the thread identifier.

[static] const IlsThreadId GetCurrentIdentifier();

This static member function returns the identifier of the current thread. Since it can be called a very large number of times, this member function is inline. Thus, the thread library adds no extra overhead when compared to the native library.

[static] void Join(IlsThread*);

This static member function can be used to keep the calling thread waiting for the termination of a given thread.

void join();

This member function is equivalent to the previous one.

[static] void Yield();

This static member function allows for another thread with the same priority or greater to be scheduled (if there are any waiting). The exact behavior of this call depends on the machine used, and therefore on the scheduling policy of the underlying operating system.

[static] void ExitCurrentThread();

This static member function terminates the calling thread without returning from the start procedure.

void addTerminatedCallback(IlsThreadTerminatedFunc, IlsAny = 0);

This member function adds a callback which is invoked when a thread exits normally. In this case, all the registered callbacks are called (in an unspecified order). The second argument is the one that is passed to the callback.

void removeTerminatedCallback(IlsThreadTerminatedFunc, IlsAny=0);

This member function removes the thread-terminated callback that was added by a call to addTerminatedCallback.

[static] IlsBoolean Mtsafe();

This static member function returns IlsTrue if the library supports multithreading. Otherwise, it returns IlsFalse.

Operators

friend ostream& operator<<(ostream&, const IlsThread&);

This operator prints the name of the object to the output stream.