[mirror_ubuntu-bionic-kernel.git] / Documentation / percpu-rw-semaphore.txt

====================
Percpu rw semaphores
====================

Percpu rw semaphores is a new read-write semaphore design that is
optimized for locking for reading.

The problem with traditional read-write semaphores is that when multiple
cores take the lock for reading, the cache line containing the semaphore
is bouncing between L1 caches of the cores, causing performance
degradation.

Locking for reading is very fast, it uses RCU and it avoids any atomic
instruction in the lock and unlock path. On the other hand, locking for
writing is very expensive, it calls synchronize_rcu() that can take
hundreds of milliseconds.

The lock is declared with "struct percpu_rw_semaphore" type.
The lock is initialized percpu_init_rwsem, it returns 0 on success and
-ENOMEM on allocation failure.
The lock must be freed with percpu_free_rwsem to avoid memory leak.

The lock is locked for read with percpu_down_read, percpu_up_read and
for write with percpu_down_write, percpu_up_write.

The idea of using RCU for optimized rw-lock was introduced by
Eric Dumazet <eric.dumazet@gmail.com>.
The code was written by Mikulas Patocka <mpatocka@redhat.com>
Commit	Line	Data
c437c3a4	1	====================
62ac665f	2	Percpu rw semaphores
c437c3a4	3	====================
62ac665f MP	4
	5	Percpu rw semaphores is a new read-write semaphore design that is
	6	optimized for locking for reading.
	7
	8	The problem with traditional read-write semaphores is that when multiple
	9	cores take the lock for reading, the cache line containing the semaphore
	10	is bouncing between L1 caches of the cores, causing performance
	11	degradation.
	12
e6b5c082	13	Locking for reading is very fast, it uses RCU and it avoids any atomic
62ac665f MP	14	instruction in the lock and unlock path. On the other hand, locking for
62ac665f MP	15	writing is very expensive, it calls synchronize_rcu() that can take
e6b5c082	16	hundreds of milliseconds.
62ac665f MP	17
	18	The lock is declared with "struct percpu_rw_semaphore" type.
	19	The lock is initialized percpu_init_rwsem, it returns 0 on success and
	20	-ENOMEM on allocation failure.
	21	The lock must be freed with percpu_free_rwsem to avoid memory leak.
	22
	23	The lock is locked for read with percpu_down_read, percpu_up_read and
	24	for write with percpu_down_write, percpu_up_write.
	25
	26	The idea of using RCU for optimized rw-lock was introduced by
	27	Eric Dumazet <eric.dumazet@gmail.com>.
	28	The code was written by Mikulas Patocka <mpatocka@redhat.com>