Provided by: manpages-dev_6.03-1_all 
NAME
membarrier - issue memory barriers on a set of threads
LIBRARY
Standard C library (libc, -lc)
SYNOPSIS
#include <linux/membarrier.h> /* Definition of MEMBARRIER_* constants */
#include <sys/syscall.h> /* Definition of SYS_* constants */
#include <unistd.h>
int syscall(SYS_membarrier, int cmd, unsigned int flags, int cpu_id);
Note: glibc provides no wrapper for membarrier(), necessitating the use of syscall(2).
DESCRIPTION
The membarrier() system call helps reducing the overhead of the memory barrier
instructions required to order memory accesses on multi-core systems. However, this
system call is heavier than a memory barrier, so using it effectively is not as simple as
replacing memory barriers with this system call, but requires understanding of the details
below.
Use of memory barriers needs to be done taking into account that a memory barrier always
needs to be either matched with its memory barrier counterparts, or that the
architecture's memory model doesn't require the matching barriers.
There are cases where one side of the matching barriers (which we will refer to as "fast
side") is executed much more often than the other (which we will refer to as "slow side").
This is a prime target for the use of membarrier(). The key idea is to replace, for these
matching barriers, the fast-side memory barriers by simple compiler barriers, for example:
asm volatile ("" : : : "memory")
and replace the slow-side memory barriers by calls to membarrier().
This will add overhead to the slow side, and remove overhead from the fast side, thus
resulting in an overall performance increase as long as the slow side is infrequent enough
that the overhead of the membarrier() calls does not outweigh the performance gain on the
fast side.
The cmd argument is one of the following:
MEMBARRIER_CMD_QUERY (since Linux 4.3)
Query the set of supported commands. The return value of the call is a bit mask of
supported commands. MEMBARRIER_CMD_QUERY, which has the value 0, is not itself
included in this bit mask. This command is always supported (on kernels where
membarrier() is provided).
MEMBARRIER_CMD_GLOBAL (since Linux 4.16)
Ensure that all threads from all processes on the system pass through a state where
all memory accesses to user-space addresses match program order between entry to
and return from the membarrier() system call. All threads on the system are
targeted by this command.
MEMBARRIER_CMD_GLOBAL_EXPEDITED (since Linux 4.16)
Execute a memory barrier on all running threads of all processes that previously
registered with MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED.
Upon return from the system call, the calling thread has a guarantee that all
running threads have passed through a state where all memory accesses to user-space
addresses match program order between entry to and return from the system call
(non-running threads are de facto in such a state). This guarantee is provided
only for the threads of processes that previously registered with
MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED.
Given that registration is about the intent to receive the barriers, it is valid to
invoke MEMBARRIER_CMD_GLOBAL_EXPEDITED from a process that has not employed
MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED.
The "expedited" commands complete faster than the non-expedited ones; they never
block, but have the downside of causing extra overhead.
MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED (since Linux 4.16)
Register the process's intent to receive MEMBARRIER_CMD_GLOBAL_EXPEDITED memory
barriers.
MEMBARRIER_CMD_PRIVATE_EXPEDITED (since Linux 4.14)
Execute a memory barrier on each running thread belonging to the same process as
the calling thread.
Upon return from the system call, the calling thread has a guarantee that all its
running thread siblings have passed through a state where all memory accesses to
user-space addresses match program order between entry to and return from the
system call (non-running threads are de facto in such a state). This guarantee is
provided only for threads in the same process as the calling thread.
The "expedited" commands complete faster than the non-expedited ones; they never
block, but have the downside of causing extra overhead.
A process must register its intent to use the private expedited command prior to
using it.
MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED (since Linux 4.14)
Register the process's intent to use MEMBARRIER_CMD_PRIVATE_EXPEDITED.
MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE (since Linux 4.16)
In addition to providing the memory ordering guarantees described in
MEMBARRIER_CMD_PRIVATE_EXPEDITED, upon return from system call the calling thread
has a guarantee that all its running thread siblings have executed a core
serializing instruction. This guarantee is provided only for threads in the same
process as the calling thread.
The "expedited" commands complete faster than the non-expedited ones, they never
block, but have the downside of causing extra overhead.
A process must register its intent to use the private expedited sync core command
prior to using it.
MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE (since Linux 4.16)
Register the process's intent to use MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE.
MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ (since Linux 5.10)
Ensure the caller thread, upon return from system call, that all its running thread
siblings have any currently running rseq critical sections restarted if flags
parameter is 0; if flags parameter is MEMBARRIER_CMD_FLAG_CPU, then this operation
is performed only on CPU indicated by cpu_id. This guarantee is provided only for
threads in the same process as the calling thread.
RSEQ membarrier is only available in the "private expedited" form.
A process must register its intent to use the private expedited rseq command prior
to using it.
MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_RSEQ (since Linux 5.10)
Register the process's intent to use MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ.
MEMBARRIER_CMD_SHARED (since Linux 4.3)
This is an alias for MEMBARRIER_CMD_GLOBAL that exists for header backward
compatibility.
The flags argument must be specified as 0 unless the command is
MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ, in which case flags can be either 0 or
MEMBARRIER_CMD_FLAG_CPU.
The cpu_id argument is ignored unless flags is MEMBARRIER_CMD_FLAG_CPU, in which case it
must specify the CPU targeted by this membarrier command.
All memory accesses performed in program order from each targeted thread are guaranteed to
be ordered with respect to membarrier().
If we use the semantic barrier() to represent a compiler barrier forcing memory accesses
to be performed in program order across the barrier, and smp_mb() to represent explicit
memory barriers forcing full memory ordering across the barrier, we have the following
ordering table for each pairing of barrier(), membarrier(), and smp_mb(). The pair
ordering is detailed as (O: ordered, X: not ordered):
barrier() smp_mb() membarrier()
barrier() X X O
smp_mb() X O O
membarrier() O O O
RETURN VALUE
On success, the MEMBARRIER_CMD_QUERY operation returns a bit mask of supported commands,
and the MEMBARRIER_CMD_GLOBAL, MEMBARRIER_CMD_GLOBAL_EXPEDITED,
MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED, MEMBARRIER_CMD_PRIVATE_EXPEDITED,
MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED, MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE, and
MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE operations return zero. On error, -1
is returned, and errno is set to indicate the error.
For a given command, with flags set to 0, this system call is guaranteed to always return
the same value until reboot. Further calls with the same arguments will lead to the same
result. Therefore, with flags set to 0, error handling is required only for the first
call to membarrier().
ERRORS
EINVAL cmd is invalid, or flags is nonzero, or the MEMBARRIER_CMD_GLOBAL command is
disabled because the nohz_full CPU parameter has been set, or the
MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE and
MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE commands are not implemented by
the architecture.
ENOSYS The membarrier() system call is not implemented by this kernel.
EPERM The current process was not registered prior to using private expedited commands.
VERSIONS
The membarrier() system call was added in Linux 4.3.
Before Linux 5.10, the prototype for membarrier() was:
int membarrier(int cmd, int flags);
STANDARDS
membarrier() is Linux-specific.
NOTES
A memory barrier instruction is part of the instruction set of architectures with weakly
ordered memory models. It orders memory accesses prior to the barrier and after the
barrier with respect to matching barriers on other cores. For instance, a load fence can
order loads prior to and following that fence with respect to stores ordered by store
fences.
Program order is the order in which instructions are ordered in the program assembly code.
Examples where membarrier() can be useful include implementations of Read-Copy-Update
libraries and garbage collectors.
EXAMPLES
Assuming a multithreaded application where "fast_path()" is executed very frequently, and
where "slow_path()" is executed infrequently, the following code (x86) can be transformed
using membarrier():
#include <stdlib.h>
static volatile int a, b;
static void
fast_path(int *read_b)
{
a = 1;
asm volatile ("mfence" : : : "memory");
*read_b = b;
}
static void
slow_path(int *read_a)
{
b = 1;
asm volatile ("mfence" : : : "memory");
*read_a = a;
}
int
main(void)
{
int read_a, read_b;
/*
* Real applications would call fast_path() and slow_path()
* from different threads. Call those from main() to keep
* this example short.
*/
slow_path(&read_a);
fast_path(&read_b);
/*
* read_b == 0 implies read_a == 1 and
* read_a == 0 implies read_b == 1.
*/
if (read_b == 0 && read_a == 0)
abort();
exit(EXIT_SUCCESS);
}
The code above transformed to use membarrier() becomes:
#define _GNU_SOURCE
#include <stdlib.h>
#include <stdio.h>
#include <unistd.h>
#include <sys/syscall.h>
#include <linux/membarrier.h>
static volatile int a, b;
static int
membarrier(int cmd, unsigned int flags, int cpu_id)
{
return syscall(__NR_membarrier, cmd, flags, cpu_id);
}
static int
init_membarrier(void)
{
int ret;
/* Check that membarrier() is supported. */
ret = membarrier(MEMBARRIER_CMD_QUERY, 0, 0);
if (ret < 0) {
perror("membarrier");
return -1;
}
if (!(ret & MEMBARRIER_CMD_GLOBAL)) {
fprintf(stderr,
"membarrier does not support MEMBARRIER_CMD_GLOBAL\n");
return -1;
}
return 0;
}
static void
fast_path(int *read_b)
{
a = 1;
asm volatile ("" : : : "memory");
*read_b = b;
}
static void
slow_path(int *read_a)
{
b = 1;
membarrier(MEMBARRIER_CMD_GLOBAL, 0, 0);
*read_a = a;
}
int
main(int argc, char *argv[])
{
int read_a, read_b;
if (init_membarrier())
exit(EXIT_FAILURE);
/*
* Real applications would call fast_path() and slow_path()
* from different threads. Call those from main() to keep
* this example short.
*/
slow_path(&read_a);
fast_path(&read_b);
/*
* read_b == 0 implies read_a == 1 and
* read_a == 0 implies read_b == 1.
*/
if (read_b == 0 && read_a == 0)
abort();
exit(EXIT_SUCCESS);
}