summaryrefslogtreecommitdiff
path: root/doc/api/libthread/index.txt
blob: 6bbe28a50f925cc9f8fb1c7fe24a7cada4ca7cad (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
{
        title:  libthread
        description:    Myrddin Thread Library
}

Libthread
---------

    pkg thread =
            trait atomic @a::(integral,numeric) =
                    xget	: (p : @a# -> @a)
                    xset	: (p : @a#, v : @a -> void)
                    xadd	: (p : @a#, v : @a -> @a)
                    xsub	: (p : @a#, v : @a -> @a)
                    xcas	: (p : @a#, old : @a, new : @a -> @a)
                    xchg	: (p : @a#, new : @a -> @a)
            ;;

            type cond = struct
                    ...
            ;;

            type mutex = struct
                    ...
            ;;	

            impl atomic int32
            impl atomic int64
            impl atomic uint32
            impl atomic uint64

            /* mutexes */
            const mkmtx	: (-> mutex)
            const mtxlock	: (mtx : mutex# -> void)
            const mtxtrylock	: (mtx : mutex# -> bool)
            const mtxunlock	: (mtx : mutex# -> void)

            /* condition variables */
            const mkcond	: (mtx : mutex# -> cond)
            const condwait	: (cond : cond# -> void)
            const condsignal	: (cond : cond# -> void)
            const condbroadcast	: (cond : cond# -> void)
    ;;

Types
-----

    type cond = struct
            ...
    ;;

Condition variable.

    type mutex = struct
            ...
    ;;	

    trait atomic @a::(integral,numeric) =
            xget	: (p : @a# -> @a)
            xset	: (p : @a#, v : @a -> void)
            xadd	: (p : @a#, v : @a -> @a)
            xsub	: (p : @a#, v : @a -> @a)
            xcas	: (p : @a#, old : @a, new : @a -> @a)
            xchg	: (p : @a#, new : @a -> @a)
    ;;


Mutex.

Functions: Mutexes
------------------

    const mkmtx	: (-> mutex)

Crates a new mutex, in the unlocked state.

    const mtxlock	: (mtx : mutex# -> void)

Locks a mutex. Blocks if the mutex is already locked.

    const mtxtrylock	: (mtx : mutex# -> bool)

Attempts to lock a mutex. Returns true if the lock was
taken successful. Returns false if the lock was not taken.

This call does not block.

    const mtxunlock	: (mtx : mutex# -> void)

Unlocks a mutex that is taken. It is a bug to call this on a mutex that you
have not successfully locked.

Functions: Condition Variables.
------------------------------

    const mkcond	: (mtx : mutex# -> cond)

Creates a condition variable. Associates the mutex with the condition
variable.

    const condwait	: (cond : cond# -> void)

Waits on the condition to be notiifed on. Must be called with the associated
mutex locked. Unlocks the mutex that is associated with the condition variable
and sleeps until someone has notified on the condition variable.

    const condsignal	: (cond : cond# -> void)

Wakes at least one waiter on the condition variable, allowing them to take the
mutex.

    const condbroadcast	: (cond : cond# -> void)

Wakes all waiters on the condition variable.