Add notes
[kopensolaris-gnu/glibc.git] / NOTES.opensolaris
1 scheduling:
2
3   The OpenSolaris kernel allows for loadable schedule classes. A scheduling
4   class has an id (pc_cid), associated name (pc_clname), and class-specific
5   scheduling information. As new schedulers are loaded, they are incrementally
6   assigned new id's.
7
8   Since id's are assigned dynamically, there is no way to statically associate
9   a class id with a posix scheduler (i.e. SCHED_*). The only exception is
10   SCHED_SYS, which is guaranteed to have cid == 0.
11
12 threads:
13
14   The sun libpthread/libthread implementation assumes a 1:1 mapping between
15   pthread_t/thread_t and lwpid_t, while NPTL maps thread descriptors to
16   pthread_t. This behaviour was added to NPTL and maybe enabled by defining
17   PTHREAD_T_IS_TID.
18
19 mutex:
20
21   Recursive locks are represented by an 8-byte counter defined by the
22   mutex_rcount macro. The maximum number of recursive waiters is
23   UCHAR_MAX (255).
24
25   Various fields are defined in a 64-bit field. 32 of the bits are used to
26   hold the owner pid. 8-bits each are used for holding the lock byte, the
27   number of waiters, and the number of spinners. Solaris defines some macros
28   for accessing these (architecture dependent of course):
29
30     mutex_lockword (32-bits): This is used if only the lock bit needs to
31       touched.
32
33     mutex_lockword64 (64-bits): This is used if you need to atomically swap
34       both the lock bytes and the owner pid. Note that where the pid portion
35       is located is dependent on byte ordering.
36
37     mutex_lockbyte (8-bits): This is the actual lock byte. It is set to 1 when
38       the lock is locked, and 0 when unlocked.
39
40     mutex_waiters (8-bits): This is set to 1 when there is another thread
41       waiting and 0 when there are no other waiters.
42
43     mutex_spinners (8-bits): This byte is apparently unused. We reuse it (as
44       mutex_cond_waiters) to mark a mutex that has been unlocked by cond_wait
45       (hence it will be reacquired later).
46
47     mutex_ownerpid (32-bits):
48
49   The mutex_owner field is a 64-bit field that stores a pointer to the owning
50   thread descriptor. It is not checked in the kernel and is only cleared by
51   the kernel during cleanup.
52
53   The kernel does not handle recursive or error-checking mutexes.
54
55   The kernel does not set mutex_lockbyte for mutexes with the
56   LOCK_PRIO_INHERIT bit set.
57
58 semaphore:
59
60 condition variable:
61
62   The cond_waiters_kernel byte is set to 1 if there are waiters on the
63   condition variable and 0 otherwise. The cond_waiters_user byte is not
64   used by the kernel.
65
66   The only clock types supported are CLOCK_REALTIME and CLOCK_HIGHRES.
67
68 reader-writer lock:
69
70   The kernel only supports shared/process reader-writer locks; the private
71   rwlock implementation must be completely implemented in libc. For the shared
72   case, readercv and writercv are used to track the owner (thread and process).
73   The sun docs also state that the sun implementation favours writers over
74   readers[0].
75
76   There is no apparent advantage in using the rwlock syscalls since any
77   private implementation that used the embedded mutex and cv's would also work
78   correctly in the shared case.
79
80   Three additional fields are included for tracking the owner (thread and
81   process) of a reader-writer lock.
82
83 [0] http://docs.sun.com/app/docs/doc/819-2243/rwlock-init-3c?a=view