220 lines
4.8 KiB
Groff
220 lines
4.8 KiB
Groff
.\" $NetBSD: mtx.3,v 1.2 2019/04/27 10:57:11 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2016 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Kamil Rytarowski.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd October 16, 2016
|
|
.Dt MTX 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mtx
|
|
.Nd mutex functions
|
|
.Sh LIBRARY
|
|
.Lb libpthread
|
|
.Sh SYNOPSIS
|
|
.In threads.h
|
|
.Ft void
|
|
.Fn mtx_destroy "mtx_t *mtx"
|
|
.Ft int
|
|
.Fn mtx_init "mtx_t *mtx" "int type"
|
|
.Ft int
|
|
.Fn mtx_lock "mtx_t *mtx"
|
|
.Ft int
|
|
.Fn mtx_timedlock "mtx_t *__restrict mtx" "const struct timespec *__restrict ts"
|
|
.Ft int
|
|
.Fn mtx_trylock "mtx_t *mtx"
|
|
.Ft int
|
|
.Fn mtx_unlock "mtx_t *mtx"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn mtx_destroy
|
|
function releases the resources of
|
|
.Fa mtx .
|
|
It is not allowed to block the same
|
|
.Fa mtx
|
|
during the
|
|
.Fn mtx_destroy
|
|
call.
|
|
.Pp
|
|
The
|
|
.Fn mtx_init
|
|
function initialized the
|
|
.Fa mtx
|
|
object uniquely identificable with the
|
|
.Fa type
|
|
properties.
|
|
The allowed values of
|
|
.Fa type
|
|
are as follows:
|
|
.Bl -column "mtx_plain | mtx_recursive"
|
|
.It Sy "Type" Ta Sy "Description"
|
|
.It Dv mtx_plain Ta basic mutex
|
|
.It Dv mtx_timed Ta mutex with timeout support
|
|
.It Dv mtx_plain | Dv mtx_recursive Ta basic recursive mutex
|
|
.It Dv mtx_timed | Dv mtx_recursive Ta recursive mutex with timeout support
|
|
.El
|
|
.Pp
|
|
The underlying
|
|
.Nx
|
|
implementation of mutex types does not distinguish between
|
|
.Dv mtx_plain
|
|
and
|
|
.Dv mtx_timed ,
|
|
however portable code must keep the distinction.
|
|
.Pp
|
|
The
|
|
.Fn mtx_lock
|
|
function locks the
|
|
.Fa mtx
|
|
object.
|
|
It is required to never lock the same
|
|
.Fa mtx
|
|
object without the
|
|
.Dv mtx_recursive
|
|
property multiple times.
|
|
If the
|
|
.Fa mtx
|
|
object is already locked by another thread,
|
|
the caller of
|
|
.Fa mtx_lock
|
|
blocks until the lock becomes available.
|
|
.Pp
|
|
The
|
|
.Fn mtx_timedlock
|
|
function tries to lock the
|
|
.Fa mtx
|
|
object.
|
|
In case of blocked resource by another thread,
|
|
this call blocks for the specified timeout in the
|
|
.Fa ts
|
|
argument.
|
|
The timeout argument is
|
|
.Dv TIME_UTC
|
|
based time of
|
|
.Dv timespec
|
|
type.
|
|
It is required to never lock the same
|
|
.Fa mtx
|
|
object without the
|
|
.Dv mtx_recursive
|
|
property multiple times.
|
|
In portable code, a
|
|
.Fa mtx
|
|
object with the
|
|
.Dv mtx_recursive
|
|
property must be used in such a case.
|
|
.Pp
|
|
The
|
|
.Fn mtx_trylock
|
|
function call attempts to lock the
|
|
.Fa mtx
|
|
object.
|
|
This function does not block if another thread already locked the
|
|
.Fa mtx
|
|
object, but immediately returns indicating proper status.
|
|
.Pp
|
|
The
|
|
.Fn mtx_unlock
|
|
function unlocks the
|
|
.Fa mtx
|
|
object.
|
|
This call must be preceded with a matching
|
|
.Fn mtx_lock
|
|
call in the same thread.
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn mtx_destroy
|
|
function returns no value.
|
|
.Pp
|
|
The
|
|
.Fn mtx_init
|
|
function returns
|
|
.Dv thrd_success
|
|
on success or
|
|
.Dv thrd_error
|
|
on failure.
|
|
.Pp
|
|
The
|
|
.Fn mtx_lock
|
|
function returns
|
|
.Dv thrd_success
|
|
on success or
|
|
.Dv thrd_error
|
|
on failure.
|
|
.Pp
|
|
The
|
|
.Fn mtx_lock
|
|
function returns
|
|
.Dv thrd_success
|
|
on success,
|
|
otherwise
|
|
.Dv thrd_timedout
|
|
to indicate that system time has reached or exceeded the time specified in
|
|
.Dv ts ,
|
|
or
|
|
.Dv thrd_error
|
|
on failure.
|
|
.Pp
|
|
The
|
|
.Fn mtx_trylock
|
|
function returns
|
|
.Dv thrd_success
|
|
on success,
|
|
otherwise
|
|
.Dv thrd_timedout
|
|
to indicate that
|
|
.Fa mtx
|
|
object is already locked, or
|
|
.Dv thrd_error
|
|
on failure.
|
|
.Pp
|
|
The
|
|
.Fn mtx_unlock
|
|
function returns
|
|
.Dv thrd_success
|
|
on success,
|
|
otherwise
|
|
.Dv thrd_timedout
|
|
to indicate that
|
|
.Fa mtx
|
|
object is already locked, or
|
|
.Dv thrd_error
|
|
on failure.
|
|
.Sh SEE ALSO
|
|
.Xr pthread_mutex 3 ,
|
|
.Xr threads 3
|
|
.Sh STANDARDS
|
|
The
|
|
.Nm
|
|
interface conforms to
|
|
.St -isoC-2011 .
|
|
.Sh HISTORY
|
|
This interface first appeared in
|
|
.Nx 9 .
|
|
.Sh AUTHORS
|
|
.An Kamil Rytarowski Aq Mt kamil@NetBSD.org
|