goto

Home

Free Source Code

Module fthreads

Fact Sheet

Email us

Purple Sage Computing Solutions, Inc.

fthreads Threads

Home --> Free Source Code --> fthreads --> fthreads Usage --> fthreads Threads

fthreads Threads

The primary thread of a Win32 process has four arguments and returns one integer value as its result. Subsequent threads have one argument and return one integer value. Using fthreads, the thread's argument is the thread variable, which is how the thread can identify itself and which is used by several of the fthreads routines. Below are links to the thread routines.

Back to the Top

Introduction to Threads

A worker thread starts execution when a function is passed to thread_create(). The thread begins executing the function asynchronously. The primary thread may wait for one thread or for a team of threads. The team is a group of threads which was made by a call to team_init(). The primary thread waits for one thread by calling thread_wait() and passing it the thread variable of the thread. The primary thread waits for a team of threads by calling thread_waitall() and passing the team variable.

A thread may be suspended by calling thread_pause() and resumed by calling thread_run(), but it is better to use synchronization objects to synchronize threads than suspends and resumes.

It may be desirable to change the priority within the process of some threads. For example, the priority of a thread dedicated to input/output processing is generally raised relative to the other threads due to the fact that it will spend much of its time suspended awaiting completion of its I/O requests. This is done by calling thread_priority(). A thread determines its own thread id, a number between one and the number of worker threads (the primary thread has a id of primary_id) by calling thread_id(). Per thread statistics may be gathered by calling thread_status().

Back to the Top

Thread Routines

thread_create()

The thread_create() routine starts a new thread executing, and provides the function it will execute.

interface
   subroutine thread_create( th, task, &
              name, trace_v, flag)
      type( thread_t), intent( out) :: th
      external task
      integer :: task
      character( len= *), optional, &
                 intent( in) :: name
      type( trace_t), optional, &
            intent( inout) :: trace_v
      integer, optional, &
               intent( out) :: flag
   end subroutine thread_create
end interface
			

The thread variable is returned, referring to the thread just created. The thread is executing integer function task. The return value of the thread may be the return value of task, if the thread exits by executing a return from task. The function task must have exactly one argument, which is the thread variable. The thread may be named by the optional character variable name. The optional type trace_t trace variable trace_v and the optional integer variable flag provide tracing and feedback.

Back to the Top

thread_wait()

The thread_wait() waits for the specified thread to exit.

interface
   subroutine thread_wait( th, trace_v, &
                           flag)
      type( thread_t), intent( in) :: th
      type( trace_t), optional, &
            intent( inout) :: trace_v
      integer, optional, &
               intent( out) :: flag
   end subroutine thread_wait
end interface
			

The subroutine thread_wait() does not return until the thread specified by the thread variable th has exited. At that time, statistics about the type thread_t thread variable th may be gathered by calling thread_status(). The optional type trace_t trace variable trace_v and the optional integer variable flag provide tracing and feedback.

Back to the Top

thread_waitall()

The thread_waitall() waits for the specified team of threads to exit.

interface
   subroutine thread_waitall( tm, &
              trace_v, flag)
      type( team_t), intent( in) :: tm
      type( trace_t), optional, &
            intent( inout) :: trace_v
      integer, optional, &
               intent( out) :: flag
   end subroutine thread_waitall
end interface
			

The subroutine thread_waitall() does not return until all the threads on the team by the team variable tm have exited. At that time, statistics about any thread on the team may be gathered by calling thread_status(). The optional type trace_t trace variable trace_v and the optional integer variable flag provide tracing and feedback.

Back to the Top

thread_return()

The thread_return() causes the specified thread to exit, and specifies the thread function return value.

interface
   subroutine thread_return( th, value, &
              trace_v)
      type( thread_t), intent( in) :: th
      integer, optional, &
               intent( in) :: value
      type( trace_t), optional, &
            intent( inout) :: trace_v
   end subroutine thread_return
end interface
			

The subroutine thread_return() causes the thread specified by thread variable th to exit and returns the value specified in optional integer value as the thread return value. If the optional integer value is absent, a value of fthread_ok is returned. The optional type trace_t trace variable allows tracing of this routine's activities. There is no flag value because normally, this routine never returns to its caller.

Back to the Top

thread_pause()

The thread_pause() causes the specified thread to be suspended.

interface
   subroutine thread_pause( th, trace_v, &
                            flag)
      type( thread_t), intent( in) :: th
      type( trace_t), optional, &
            intent( inout) :: trace_v
      integer, optional, &
               intent( out) :: flag
   end subroutine thread_pause
end interface
			

The subroutine thread_pause() causes the thread specified by thread variable th to be suspended. The optional type trace_t trace variable trace_v and the optional integer variable flag provide tracing and feedback.

Back to the Top

thread_run()

The thread_run() causes the specified thread to be resumed.

interface
   subroutine thread_run( th, trace_v, &
                          flag)
      type( thread_t), intent( in) :: th
      type( trace_t), optional, &
            intent( inout) :: trace_v
      integer, optional, &
               intent( out) :: flag
   end subroutine thread_run
end interface
			

The subroutine thread_run() causes the thread specified by thread variable th to be resumed. The optional type trace_t trace variable trace_v and the optional integer variable flag provide tracing and feedback.

Back to the Top

thread_id()

The thread_id() return the thread id.

interface
   integer function thread_id( th)
      type( thread_t), intent( in) :: th
   end function thread_id
end interface
			

The integer function thread_id() returns the thread id. The thread id is a positive integer from one through the number of threads.

Back to the Top

thread_priority()

The thread_priority() returns or sets the thread's intraprocess priority.

interface
   subroutine thread_priority( th, get, &
              set, trace_v, flag)
      type( thread_t), intent( in) :: th
      integer, optional, &
               intent( out) :: get
      integer, optional, &
               intent( in) :: set
      type( trace_t), optional, &
            intent( inout) :: trace_v
      integer, optional, &
               intent( out) :: flag
   end subroutine thread_priority
end interface
			

The subroutine thread_priority() returns or sets the thread's intraprocess priority. This priority is described by one of the Win32 thread priority constants. The optional type trace_t trace variable trace_v and the optional integer variable flag provide tracing and feedback.

Back to the Top

thread_status()

The thread_status() returns thread statistics about the specified thread.

interface
   subroutine thread_status( th, name, &
             value, et, st, trace_v, flag)
      type( thread_t), intent( in) :: th
      character( len= *), optional, &
                 intent( out) :: name
      integer, optional, &
               intent( out) :: value
      real, optional, intent( out) :: et
      real, optional, intent( out) :: st
      type( trace_t), optional, &
            intent( inout) :: trace_v
      integer, optional, &
               intent( out) :: flag
   end subroutine thread_status
end interface
			

The subroutine thread_status() returns thread statistics about the thread specified by thread variable th. The thread's name may be returned by the optional character variable name. The thread's return value may be returned by the optional integer variable value. The thread's user time and kernel time may be returned by the optional real variables et and st, respectively. The optional type trace_t trace variable trace_v and the optional integer variable flag provide tracing and feedback.

Back to the Top

Please see our Fact Sheet, or E-mail us for more information.

Home - Fact Sheet - Free Source Code - Fortran Links - Email us

Back to the Top