File : g-thread.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT RUN-TIME COMPONENTS --
4 -- --
5 -- G N A T . T H R E A D S --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1998-2010, AdaCore --
10 -- --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. --
17 -- --
18 -- --
19 -- --
20 -- --
21 -- --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
26 -- --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
29 -- --
30 ------------------------------------------------------------------------------
31
32 -- This package provides facilities for creation or registration of foreign
33 -- threads for use as Ada tasks. In order to execute general Ada code, the
34 -- run-time system must know about all tasks. This package allows foreign
35 -- code, e.g. a C program, to create a thread that the Ada run-time knows
36 -- about, or to register the current thread.
37
38 -- For some implementations of GNAT Pro, the registration of foreign threads
39 -- is automatic. However, in such implementations, if the Ada program has no
40 -- tasks at all and no tasking constructs other than delay, then by default
41 -- the non-tasking version of the Ada run-time will be loaded. If foreign
42 -- threads are present, it is important to ensure that the tasking version
43 -- of the Ada run time is loaded. This may be achieved by adding "with
44 -- GNAT.Threads" to any unit in the partition.
45
46 with System;
47 with Ada.Task_Identification;
48
49 package GNAT.Threads is
50
51 type Void_Ptr is access all Integer;
52
53 function Create_Thread
54 (Code : System.Address; -- pointer
55 Parm : Void_Ptr; -- pointer
56 Size : Natural; -- int
57 Prio : Integer) -- int
58 return System.Address;
59 pragma Export (C, Create_Thread, "__gnat_create_thread");
60 -- Creates a thread with the given (Size) stack size in bytes, and
61 -- the given (Prio) priority. The task will execute a call to the
62 -- procedure whose address is given by Code. This procedure has
63 -- the prototype
64 --
65 -- void thread_code (void *id, void *parm);
66 --
67 -- where id is the id of the created task, and parm is the parameter
68 -- passed to Create_Thread. The called procedure is the body of the
69 -- code for the task, the task will be automatically terminated when
70 -- the procedure returns.
71 --
72 -- This function returns the Ada Id of the created task that can then be
73 -- used as a parameter to the procedures below.
74 --
75 -- C declaration:
76 --
77 -- extern void *__gnat_create_thread
78 -- (void (*code)(void *, void *), void *parm, int size, int prio);
79
80 function Register_Thread return System.Address;
81 pragma Export (C, Register_Thread, "__gnat_register_thread");
82 -- Create an Ada task Id for the current thread if needed.
83 -- If the thread could not be registered, System.Null_Address is returned.
84 --
85 -- This function returns the Ada Id of the current task that can then be
86 -- used as a parameter to the procedures below.
87 --
88 -- C declaration:
89 --
90 -- extern void *__gnat_register_thread ();
91 --
92 -- Here is a typical usage of the Register/Unregister_Thread procedures:
93 --
94 -- void thread_body ()
95 -- {
96 -- void *task_id = __gnat_register_thread ();
97 -- ... thread body ...
98 -- __gnat_unregister_thread ();
99 -- }
100
101 procedure Unregister_Thread;
102 pragma Export (C, Unregister_Thread, "__gnat_unregister_thread");
103 -- Unregister the current task from the GNAT run time and destroy the
104 -- memory allocated for its task id.
105 --
106 -- C declaration:
107 --
108 -- extern void __gnat_unregister_thread ();
109
110 procedure Unregister_Thread_Id (Thread : System.Address);
111 pragma Export (C, Unregister_Thread_Id, "__gnat_unregister_thread_id");
112 -- Unregister the task associated with Thread from the GNAT run time and
113 -- destroy the memory allocated for its task id.
114 -- If no task id is associated with Thread, do nothing.
115 --
116 -- C declaration:
117 --
118 -- extern void __gnat_unregister_thread_id (pthread_t *thread);
119
120 procedure Destroy_Thread (Id : System.Address);
121 pragma Export (C, Destroy_Thread, "__gnat_destroy_thread");
122 -- This procedure may be used to prematurely abort the created thread.
123 -- The value Id is the value that was passed to the thread code procedure
124 -- at activation time.
125 --
126 -- C declaration:
127 --
128 -- extern void __gnat_destroy_thread (void *id);
129
130 procedure Get_Thread (Id : System.Address; Thread : System.Address);
131 pragma Export (C, Get_Thread, "__gnat_get_thread");
132 -- This procedure is used to retrieve the thread id of a given task.
133 -- The value Id is the value that was passed to the thread code procedure
134 -- at activation time.
135 -- Thread is a pointer to a thread id that will be updated by this
136 -- procedure.
137 --
138 -- C declaration:
139 --
140 -- extern void __gnat_get_thread (void *id, pthread_t *thread);
141
142 function To_Task_Id
143 (Id : System.Address)
144 return Ada.Task_Identification.Task_Id;
145 -- Ada interface only.
146 -- Given a low level Id, as returned by Create_Thread, return a Task_Id,
147 -- so that operations in Ada.Task_Identification can be used.
148
149 end GNAT.Threads;