hDsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget(/translations/zh_CN/userspace-api/futex2modnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/zh_TW/userspace-api/futex2modnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/it_IT/userspace-api/futex2modnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ja_JP/userspace-api/futex2modnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ko_KR/userspace-api/futex2modnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/sp_SP/userspace-api/futex2modnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhB/var/lib/git/docbuild/linux/Documentation/userspace-api/futex2.rsthKubhsection)}(hhh](htitle)}(hfutex2h]hfutex2}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh field_list)}(hhh]hfield)}(hhh](h field_name)}(hAuthorh]hAuthor}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhKubh field_body)}(h+André Almeida h]h paragraph)}(h*André Almeida h](hAndré Almeida <}(hhhhhNhNubh reference)}(handrealmeid@collabora.comh]handrealmeid@collabora.com}(hhhhhNhNubah}(h]h ]h"]h$]h&]refuri mailto:andrealmeid@collabora.comuh1hhhubh>}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hX#futex, or fast user mutex, is a set of syscalls to allow userspace to create performant synchronization mechanisms, such as mutexes, semaphores and conditional variables in userspace. C standard libraries, like glibc, uses it as a means to implement more high level interfaces like pthreads.h]hX#futex, or fast user mutex, is a set of syscalls to allow userspace to create performant synchronization mechanisms, such as mutexes, semaphores and conditional variables in userspace. C standard libraries, like glibc, uses it as a means to implement more high level interfaces like pthreads.}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hvfutex2 is a followup version of the initial futex syscall, designed to overcome limitations of the original interface.h]hvfutex2 is a followup version of the initial futex syscall, designed to overcome limitations of the original interface.}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hUser APIh]hUser API}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj=hhhhhKubh)}(hhh](h)}(h``futex_waitv()``h]hliteral)}(hjSh]h futex_waitv()}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjQubah}(h]h ]h"]h$]h&]uh1hhjNhhhhhKubh)}(h*Wait on an array of futexes, wake on any::h]h)Wait on an array of futexes, wake on any:}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjNhhubh literal_block)}(hfutex_waitv(struct futex_waitv *waiters, unsigned int nr_futexes, unsigned int flags, struct timespec *timeout, clockid_t clockid) struct futex_waitv { __u64 val; __u64 uaddr; __u32 flags; __u32 __reserved; };h]hfutex_waitv(struct futex_waitv *waiters, unsigned int nr_futexes, unsigned int flags, struct timespec *timeout, clockid_t clockid) struct futex_waitv { __u64 val; __u64 uaddr; __u32 flags; __u32 __reserved; };}hjzsbah}(h]h ]h"]h$]h&]hhuh1jxhhhKhjNhhubh)}(hXUserspace sets an array of struct futex_waitv (up to a max of 128 entries), using ``uaddr`` for the address to wait for, ``val`` for the expected value and ``flags`` to specify the type (e.g. private) and size of futex. ``__reserved`` needs to be 0, but it can be used for future extension. The pointer for the first item of the array is passed as ``waiters``. An invalid address for ``waiters`` or for any ``uaddr`` returns ``-EFAULT``.h](hRUserspace sets an array of struct futex_waitv (up to a max of 128 entries), using }(hjhhhNhNubjV)}(h ``uaddr``h]huaddr}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh for the address to wait for, }(hjhhhNhNubjV)}(h``val``h]hval}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh for the expected value and }(hjhhhNhNubjV)}(h ``flags``h]hflags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh7 to specify the type (e.g. private) and size of futex. }(hjhhhNhNubjV)}(h``__reserved``h]h __reserved}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubhr needs to be 0, but it can be used for future extension. The pointer for the first item of the array is passed as }(hjhhhNhNubjV)}(h ``waiters``h]hwaiters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh. An invalid address for }(hjhhhNhNubjV)}(h ``waiters``h]hwaiters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh or for any }(hjhhhNhNubjV)}(h ``uaddr``h]huaddr}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh returns }(hjhhhNhNubjV)}(h ``-EFAULT``h]h-EFAULT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK#hjNhhubh)}(hIf userspace has 32-bit pointers, it should do a explicit cast to make sure the upper bits are zeroed. ``uintptr_t`` does the tricky and it works for both 32/64-bit pointers.h](hgIf userspace has 32-bit pointers, it should do a explicit cast to make sure the upper bits are zeroed. }(hj&hhhNhNubjV)}(h ``uintptr_t``h]h uintptr_t}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1jUhj&ubh: does the tricky and it works for both 32/64-bit pointers.}(hj&hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK*hjNhhubh)}(hz``nr_futexes`` specifies the size of the array. Numbers out of [1, 128] interval will make the syscall return ``-EINVAL``.h](jV)}(h``nr_futexes``h]h nr_futexes}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjFubh` specifies the size of the array. Numbers out of [1, 128] interval will make the syscall return }(hjFhhhNhNubjV)}(h ``-EINVAL``h]h-EINVAL}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjFubh.}(hjFhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK.hjNhhubh)}(h]The ``flags`` argument of the syscall needs to be 0, but it can be used for future extension.h](hThe }(hjthhhNhNubjV)}(h ``flags``h]hflags}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjtubhP argument of the syscall needs to be 0, but it can be used for future extension.}(hjthhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK1hjNhhubh)}(hX For each entry in ``waiters`` array, the current value at ``uaddr`` is compared to ``val``. If it's different, the syscall undo all the work done so far and return ``-EAGAIN``. If all tests and verifications succeeds, syscall waits until one of the following happens:h](hFor each entry in }(hjhhhNhNubjV)}(h ``waiters``h]hwaiters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh array, the current value at }(hjhhhNhNubjV)}(h ``uaddr``h]huaddr}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh is compared to }(hjhhhNhNubjV)}(h``val``h]hval}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubhL. If it’s different, the syscall undo all the work done so far and return }(hjhhhNhNubjV)}(h ``-EAGAIN``h]h-EAGAIN}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh\. If all tests and verifications succeeds, syscall waits until one of the following happens:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK4hjNhhubh bullet_list)}(hhh](h list_item)}(h-The timeout expires, returning ``-ETIMEOUT``.h]h)}(hjh](hThe timeout expires, returning }(hjhhhNhNubjV)}(h ``-ETIMEOUT``h]h -ETIMEOUT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK9hjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hCA signal was sent to the sleeping task, returning ``-ERESTARTSYS``.h]h)}(hjh](h2A signal was sent to the sleeping task, returning }(hjhhhNhNubjV)}(h``-ERESTARTSYS``h]h -ERESTARTSYS}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK:hjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hKSome futex at the list was woken, returning the index of some waked futex. h]h)}(hJSome futex at the list was woken, returning the index of some waked futex.h]hJSome futex at the list was woken, returning the index of some waked futex.}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK;hjCubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhK9hjNhhubh)}(hrAn example of how to use the interface can be found at ``tools/testing/selftests/futex/functional/futex_waitv.c``.h](h7An example of how to use the interface can be found at }(hjchhhNhNubjV)}(h:``tools/testing/selftests/futex/functional/futex_waitv.c``h]h6tools/testing/selftests/futex/functional/futex_waitv.c}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjcubh.}(hjchhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK=hjNhhubeh}(h] futex-waitvah ]h"] futex_waitv()ah$]h&]uh1hhj=hhhhhKubh)}(hhh](h)}(hTimeouth]hTimeout}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK@ubh)}(hX``struct timespec *timeout`` argument is an optional argument that points to an absolute timeout. You need to specify the type of clock being used at ``clockid`` argument. ``CLOCK_MONOTONIC`` and ``CLOCK_REALTIME`` are supported. This syscall accepts only 64bit timespec structs.h](jV)}(h``struct timespec *timeout``h]hstruct timespec *timeout}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubhz argument is an optional argument that points to an absolute timeout. You need to specify the type of clock being used at }(hjhhhNhNubjV)}(h ``clockid``h]hclockid}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh argument. }(hjhhhNhNubjV)}(h``CLOCK_MONOTONIC``h]hCLOCK_MONOTONIC}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubh and }(hjhhhNhNubjV)}(h``CLOCK_REALTIME``h]hCLOCK_REALTIME}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubhA are supported. This syscall accepts only 64bit timespec structs.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKBhjhhubeh}(h]timeoutah ]h"]timeoutah$]h&]uh1hhj=hhhhhK@ubh)}(hhh](h)}(hTypes of futexh]hTypes of futex}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKHubh)}(hXA futex can be either private or shared. Private is used for processes that shares the same memory space and the virtual address of the futex will be the same for all processes. This allows for optimizations in the kernel. To use private futexes, it's necessary to specify ``FUTEX_PRIVATE_FLAG`` in the futex flag. For processes that doesn't share the same memory space and therefore can have different virtual addresses for the same futex (using, for instance, a file-backed shared memory) requires different internal mechanisms to be get properly enqueued. This is the default behavior, and it works with both private and shared futexes.h](hXA futex can be either private or shared. Private is used for processes that shares the same memory space and the virtual address of the futex will be the same for all processes. This allows for optimizations in the kernel. To use private futexes, it’s necessary to specify }(hjhhhNhNubjV)}(h``FUTEX_PRIVATE_FLAG``h]hFUTEX_PRIVATE_FLAG}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubhXZ in the futex flag. For processes that doesn’t share the same memory space and therefore can have different virtual addresses for the same futex (using, for instance, a file-backed shared memory) requires different internal mechanisms to be get properly enqueued. This is the default behavior, and it works with both private and shared futexes.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKJhjhhubh)}(hFutexes can be of different sizes: 8, 16, 32 or 64 bits. Currently, the only supported one is 32 bit sized futex, and it need to be specified using ``FUTEX_32`` flag.h](hFutexes can be of different sizes: 8, 16, 32 or 64 bits. Currently, the only supported one is 32 bit sized futex, and it need to be specified using }(hj'hhhNhNubjV)}(h ``FUTEX_32``h]hFUTEX_32}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1jUhj'ubh flag.}(hj'hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKThjhhubeh}(h]types-of-futexah ]h"]types of futexah$]h&]uh1hhj=hhhhhKHubeh}(h]user-apiah ]h"]user apiah$]h&]uh1hhhhhhhhKubeh}(h]futex2ah ]h"]futex2ah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j\jYjTjQjjjjjLjIu nametypes}(j\jTjjjLuh}(jYhjQj=jjNjjjIju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.