1 package frost.threads
2
3 uses frost.unsafe.UnsafeMessageQueue
4
5 ====================================================================================================
6 Represents a thread of execution within a program. Each program begins with a single thread, and may
7 create more. By default, any living threads prevent a program from exiting, even if its `main()`
8 method ends. The optional `preventsExit` argument to `run()` changes this behavior.
9
10 As Frost has neither global nor class-level mutable variables, threads do not normally have any
11 access to each other's mutable data. Eliminating memory sharing means that there is generally no
12 need for mutexes, semaphores, or other common thread synchronization constructs; mutable objects are
13 only accessible from a single thread each and there is therefore no contention.
14
15 Threads communicate with each other using [MessageQueue] objects, which only permit [Immutable]
16 objects to be sent. This ensures that only one thread can access a given mutable object at a time.
17
18 In situations where it is actually necessary to have multiple threads access potentially-shared
19 mutable objects, the [UnsafeMessageQueue] class allows for passing mutable objects between threads.
20 If the object (including any other mutable objects it directly or indirectly points to) is truly
21 'handed off' and no longer accessed by the sending thread, no danger exists. If the sending thread
22 continues to access a shared object, [Lock] must be used to synchronize access.
23 ====================================================================================================
24 class Thread : Immutable {
25 @private
26 def nativeHandle:Int
27
28 @private
29 init() {
30 }
31
32 @private
33 @external(frostThreadRun)
34 method run(m:()=&>(), preventsExit:Bit)
35
36 ================================================================================================
37 Creates and starts a new thread which executes the specified method. For example, to create a
38 new thread which continually displays a message to the console:
39
40 Thread.start(method() {
41 loop {
42 Console.printLine("Hi, I'm a thread!")
43 }
44 })
45
46 @param run the run method to execute
47 @returns the newly created thread
48 ================================================================================================
49 @class
50 method start(run:()=&>*()):Thread {
51 def result := Thread()
52 result.run(run, true)
53 return result
54 }
55
56 @class
57 method start(run:()=&>*(), preventsExit:Bit):Thread {
58 var result := Thread()
59 result.run(run, preventsExit)
60 return result
61 }
62
63 @class
64 method unsafeStart(run:()=&>()):Thread {
65 def result := Thread()
66 result.run(run, true)
67 return result
68 }
69
70 @class
71 method unsafeStart(run:()=&>(), preventsExit:Bit):Thread {
72 var result := Thread()
73 result.run(run, preventsExit)
74 return result
75 }
76
77 ================================================================================================
78 Waits for this thread to exit.
79 ================================================================================================
80 @external(frostThreadWaitFor)
81 method waitFor()
82
83 ================================================================================================
84 Returns the number of threads that generally leads to best performance on the current system.
85 This will generally be (but is not necessarily) the number of available processor cores.
86
87 **IMPLEMENTATION NOTE:** this is not currently implemented and is just
88 hardcoded to return 8.
89
90 @returns the preferred number of executing threads
91 ================================================================================================
92 @class
93 function preferredThreadCount():Int {
94 return 8
95 }
96
97 ================================================================================================
98 Pauses execution of the current thread for a length of time.
99
100 @param the number of seconds (or fraction thereof) to sleep
101 ================================================================================================
102 @class
103 @external(frostThreadSleep)
104 method sleep(seconds:Real64)
105 }