.\" Copyright (c) 2001-2002 Packet Design, LLC. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, .\" use and redistribution of this software, in source or object code .\" forms, with or without modifications are expressly permitted by .\" Packet Design; provided, however, that: .\" .\" (i) Any and all reproductions of the source or object code .\" must include the copyright notice above and the following .\" disclaimer of warranties; and .\" (ii) No rights are granted, in any manner or form, to use .\" Packet Design trademarks, including the mark "PACKET DESIGN" .\" on advertising, endorsements, or otherwise except as such .\" appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 PACKET DESIGN IS ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $Id: paction.3,v 1.1.1.1 2012/02/21 23:25:53 misho Exp $ .\" .Dd April 22, 2002 .Dt PACTION 3 .Os .Sh NAME .Nm paction .Nd actions in a separate thread .Sh LIBRARY PDEL Library (libpdel, \-lpdel) .Sh SYNOPSIS .In sys/types.h .In pthread.h .In pdel/util/paction.h .Ft int .Fn paction_start "struct paction **actionp" "pthread_mutex_t *mutex" "paction_handler_t *handler" "paction_finish_t *finish" "void *arg" .Ft void .Fn paction_cancel "struct paction **actionp" .Sh DESCRIPTION These functions provide support for .Em actions , which are simply function invocations that happen in separate threads. This is just a simplified API for spawning and cancelling threads with built-in support for mutex locking and avoiding certain race conditions. .Pp .Fn paction_start creates a new action and stores a pointer to the action, represented by a .Li "struct paction" , in .Fa "*actionp" . The creation of an action results in .Fn handler being invoked in a new thread. .Fn paction_cancel cancels an action by canceling its associated thread. In any case, when the action has completed, .Fn finish is invoked. If the action was not canceled via .Fn paction_cancel , then .Fa "*mutex" is acquired before .Fn finish is invoked and released afterward. If .Fn paction_cancel was called, then the mutex is not acquired for .Fn finish . The .Fa was_canceled argument to .Fn finish reflects this. .Pp .Fa handler and .Fa finish must be pointers to functions having these types: .Pp .Bd -literal -compact -offset 3n typedef void paction_handler_t(void *arg); typedef void paction_finish_t(void *arg, int was_canceled); .Ed .Pp When .Fn paction_start is invoked, .Fa "*actionp" must be .Dv NULL . As long as the action is still in progress (i.e., .Fn finish has not yet been invoked), .Fa "*actionp" will be non-NULL. When the action completes or is canceled, .Fa "*actionp" is set to .Dv NULL again. Therefore, .Fa "*actionp" must remain valid and unmodified for the duration of the action, and can be used as an indicator of whether the action has completed. .Pp .Fn paction_cancel cancels an outstanding action. This results in the action thread being canceled at the next cancellation point. Therefore, .Fn handler may need to register thread cleanup hooks in order to free any allocated resources in the case of cancellation. Upon return, .Fa "*actionp" is set to .Dv NULL . If .Fa "*actionp" is already .Dv NULL when .Fn paction_cancel is invoked, nothing happens. .Pp In any case, .Fn finish is invoked when the action terminates. There are two reasons for an action terminating: either the action terminated normally, or .Fn paction_cancel was invoked. If the action terminated normally, .Fa "*mutex" is locked, .Fa "*actionp" is set to .Dv NULL , and .Fn finish is invoked with .Fa was_canceled set to zero. When .Fn finish returns .Fa *mutex is unlocked. .Pp If the action was canceled by .Fn paction_cancel , then neither .Fa "mutex" nor .Fa "actionp" are dereferenced; .Fn final is simply called with .Fa was_canceled set to non-zero. Note that .Fa "*actionp" will have already been set to .Dv NULL previously by .Fn paction_cancel . .Pp Cancelling the action thread directly via .Xr pthread_cancel 3 is treated just as if .Fn handler returned early; i.e., the first case above. .\" .Ss Synchronization .\" There are inherent race conditions between an action's .Fn finish function being invoked and reading the value of .Fa "*actionp" or canceling the action with .Fn paction_cancel . The .Fa "*mutex" should be used to avoid these problems by using it to protect .Fa "*actionp" . .Pp The user code should acquire .Fa "*mutex" before calling .Fn paction_start or .Fn paction_cancel , or before accessing .Fa "*actionp" . If this protocol is followed, then .Fa "*actionp" will be non-NULL if and only if the action is still pending, i.e., .Fn finish has not yet been invoked. In addition, the .Fa was_canceled argument will always be accurate, i.e., be non-zero if and only if .Fn paction_cancel was called to cancel the action. .Pp Finally, .Fa "mutex" and .Fa "actionp" will not be dereferenced after a call to .Fn paction_cancel , so it is always safe to destroy the memory pointed to by .Fa "mutex" and .Fa "actionp" after calling .Fn paction_cancel . However, .Fa arg must remain valid until .Fn finish is invoked, which may occur .Em after .Fn paction_cancel returns; alternatively, .Fn finish must not dereference .Fa arg if .Fa was_canceled is non-zero. .Sh RETURN VALUES .Fn paction_start returns -1 if there is an error, with .Va errno set appropriately. In particular, if .Fa "*actionp" is not equal to .Dv NULL , then .Va errno will be set to .Er EBUSY . .Sh SEE ALSO .Xr libpdel 3 , .Xr pevent 3 , .Xr pthread_cancel 3 , .Xr pthread_create 3 .Sh HISTORY The PDEL library was developed at Packet Design, LLC. .Dv "http://www.packetdesign.com/" .Sh AUTHORS .An Archie Cobbs Aq archie@freebsd.org