All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
qore_thread.h File Reference

### (5431)

`#include <stdio.h>`
`#include <pthread.h>`
Include dependency graph for qore_thread.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Classes

class | ThreadCleanupList
| list of functions to be run when a thread ends; required for some external libraries that require explicit cleanup when a thread terminates More...
class | QoreForeignThreadHelper
| use this class to temporarily register and deregister a foreign thread to allow Qore code to be executed and the Qore library to be used from threads not created by the Qore library More...

## Macros

#define | QFT_OK 0
| OK response when calling q_register_foreign_thread()
#define | QFT_ERROR -1
| error when calling q_register_foreign_thread()
#define | QFT_REGISTERED -2
| thread already registered when calling q_register_foreign_thread()

## Typedefs

typedef void(* | qtdest_t )(void *)
| pointer to a qore thread destructor function
typedef void(* | qtrdest_t )(void *, ExceptionSink *)
| pointer to a qore thread resource destructor function

## Functions

DLLEXPORT bool | is_valid_qore_thread ()
| returns true if the current thread is a valid qore thread; it is not safe to call most Qore functions unless the thread is registered with Qore
DLLEXPORT int | gettid ()
| returns the current TID number
DLLEXPORT QoreProgram * | getProgram ()
| returns the current QoreProgram
DLLEXPORT const AbstractQoreZoneInfo * | currentTZ ()
| returns the current local time zone, note that if 0 = UTC
DLLEXPORT void | set_thread_resource (AbstractThreadResource *atr)
| save a resource against a thread for thread resource handling
DLLEXPORT int | remove_thread_resource (AbstractThreadResource *atr)
| remove the resource from the thread resource list for the current thread
DLLEXPORT void | set_thread_resource_id (q_trid_t trid, AbstractThreadResource *atr)
| save a resource against a thread for thread resource handling using the thread resource id
DLLEXPORT int | remove_thread_resource_id (q_trid_t trid)
| remove the resource from the thread resource list for the current thread using the thread resource ID
DLLEXPORT bool | check_thread_resource_id (q_trid_t trid)
| check if a thread resouce has been saved with the given resource id
DLLEXPORT q_trid_t | qore_get_trid ()
| get a thread resource ID
DLLEXPORT int | q_register_foreign_thread ()
| registers the current thread as a Qore thread; returns QFT_OK (0) if the thread was successfully registered, QFT_ERROR (-1) if an error occurred, or QFT_REGISTERED (-2) if it was already registered
DLLEXPORT int | q_deregister_foreign_thread ()
| deregisters the current thread as a foreign thread
DLLEXPORT int | q_reserve_foreign_thread_id ()
| reserves a thread ID for later registration and returns the TID reserved; use q_release_reserved_foreign_thread_id() to release the reservation
DLLEXPORT int | q_release_reserved_foreign_thread_id (int tid)
| releases a TID reserved with q_reserve_foreign_thread_id()
DLLEXPORT int | q_register_reserved_foreign_thread (int tid)
| registers a foreign qore thread as a Qore thread with a reserved TID
DLLEXPORT int | q_deregister_reserved_foreign_thread ()
| deregisters a foreign qore thread but retains the TID as reserved

## Variables

DLLEXPORT ThreadCleanupList | tclist
| the interface to the thread cleanup list

## Detailed Description

Provides definitions relative to threading in Qore.

## Function Documentation

DLLEXPORT bool check_thread_resource_id | ( | q_trid_t | trid | ) |

check if a thread resouce has been saved with the given resource id

Parameters

  trid | thread resource id to check

Returns
  true if saved, false if not saved

DLLEXPORT bool is_valid_qore_thread | ( |  | ) |

returns true if the current thread is a valid qore thread; it is not safe to call most Qore functions unless the thread is registered with Qore

See Also
  - QoreForeignThreadHelper
  - q_register_foreign_thread()
  - q_deregister_foreign_thread()

DLLEXPORT int q_deregister_foreign_thread | ( |  | ) |

deregisters the current thread as a foreign thread

Returns
  0 if the foreign thread was deregistered, -1 if it was not registered or was not a foreign thread

See Also
  - QoreForeignThreadHelper
  - q_register_foreign_thread()
  - is_valid_qore_thread();

Since
  Qore 0.8.7

DLLEXPORT int q_deregister_reserved_foreign_thread | ( |  | ) |

deregisters a foreign qore thread but retains the TID as reserved

Returns
  0 for OK, -1 for error (TID invalid or not foreign)

Since
  Qore 0.8.7

DLLEXPORT int q_register_foreign_thread | ( |  | ) |

registers the current thread as a Qore thread; returns QFT_OK (0) if the thread was successfully registered, QFT_ERROR (-1) if an error occurred, or QFT_REGISTERED (-2) if it was already registered

call q_deregister_foreign_thread() when Qore functionality is no longer required; not calling q_deregister_foreign_thread() will cause a memory leak

Returns
  see Return Value Codes for q_register_foreign_thread() for return values

See Also
  - QoreForeignThreadHelper
  - q_deregister_foreign_thread()
  - is_valid_qore_thread();

Since
  Qore 0.8.7

DLLEXPORT int q_register_reserved_foreign_thread | ( | int | tid | ) |

registers a foreign qore thread as a Qore thread with a reserved TID

Parameters

  tid | the TID reserved with q_reserve_foreign_thread_id()

Returns
  0 for OK, -1 for error (TID invalid or not reserved)

Since
  Qore 0.8.7

DLLEXPORT int q_release_reserved_foreign_thread_id | ( | int | tid | ) |

releases a TID reserved with q_reserve_foreign_thread_id()

Parameters

  tid | the TID reserved with q_reserve_foreign_thread_id()

Returns
  0 for OK, -1 for error (TID invalid or not reserved)

Since
  Qore 0.8.7

DLLEXPORT int q_reserve_foreign_thread_id | ( |  | ) |

reserves a thread ID for later registration and returns the TID reserved; use q_release_reserved_foreign_thread_id() to release the reservation

Returns
  the TID reserved or -1 if an error occurred (thread table full)

Since
  Qore 0.8.7

DLLEXPORT int remove_thread_resource | ( | AbstractThreadResource * | atr | ) |

remove the resource from the thread resource list for the current thread

Parameters

  atr | a pointer to the thread resource to remove

Returns
  0 if successful (resource was found and removed), -1 if the resource was not found

DLLEXPORT int remove_thread_resource_id | ( | q_trid_t | trid | ) |

remove the resource from the thread resource list for the current thread using the thread resource ID

Parameters

  trid | thread resource id of the resource to remove, must have been set with set_thread_resource_id()

Returns
  0 if successful (resource was found and removed), -1 if the resource was not found

See Also
  qore_get_trid()
  set_thread_resource_id()

DLLEXPORT void set_thread_resource | ( | AbstractThreadResource * | atr | ) |

save a resource against a thread for thread resource handling

Parameters

  atr | a pointer to the thread resource to save

DLLEXPORT void set_thread_resource_id | ( | q_trid_t | trid,
|  | AbstractThreadResource * | atr
| ) |  |

save a resource against a thread for thread resource handling using the thread resource id

by using the thread resource id, you can quickly check if the resource has already been saved for the thread

Parameters

  trid | thread resource id
  atr | a pointer to the thread resource to save

See Also
  qore_get_trid()
  remove_thread_resource_id()