.\"	$NetBSD: puffs_req.3,v 1.3 2007/05/09 18:36:52 pooka Exp $
.\"
.\" Copyright (c) 2007 Antti Kantee.  All rights reserved.
.\"
.\" 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 AUTHOR 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 AUTHOR 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 May 9, 2007
.Dt PUFFS_REQ 3
.Os
.Sh NAME
.Nm puffs_req
.Nd puffs request handling
.Sh LIBRARY
.Lb libpuffs
.Sh SYNOPSIS
.In puffs.h
.Ft struct puffs_getreq *
.Fn puffs_req_makeget "struct puffs_usermount *pu" "size_t buflen" "int maxops"
.Ft int
.Fn puffs_req_loadget "struct puffs_getreq *pgr"
.Ft struct puffs_req *
.Fn puffs_req_get "struct puffs_getreq *pgr"
.Ft int
.Fn puffs_req_remainingget "struct puffs_getreq *pgr"
.Ft void
.Fn puffs_req_setmaxget "struct puffs_getreq *pgr" "int maxops"
.Ft void
.Fn puffs_req_destroyget "struct puffs_getreq *pgr"
.Ft struct puffs_putreq *
.Fn puffs_req_makeput "struct puffs_usermount *pu"
.Ft void
.Fn puffs_req_put "struct puffs_putreq *ppr" "struct puffs_req *preq"
.Ft void
.Fn puffs_req_putcc "struct puffs_putreq *ppr" "struct puffs_cc *pcc"
.Ft int
.Fn puffs_req_putput "struct puffs_putreq *ppr"
.Ft void
.Fn puffs_req_resetput "struct puffs_putreq *ppr"
.Ft void
.Fn puffs_req_destroyput "struct puffs_putreq *ppr"
.Ft int
.Fo puffs_req_handle
.Fa "struct puffs_getreq *pgr" "struct puffs_putreq *ppr" "int maxops"
.Fc
.Ft int
.Fo puffs_dopreq
.Fa "struct puffs_usermount *pu" "struct puffs_req *preq"
.Fa "struct puffs_putreq *ppr"
.Fc
.Sh DESCRIPTION
.Em IMPORTANT NOTE!
This document describes interfaces which are not yet guaranteed to be
stable.
In case you update your system sources, please recompile everything
and fix complation errors.
If your sources are out-of-sync, incorrect operation may result.
The interfaces in this document will most likely be hugely simplified
in later versions or made transparent to the implementation.
THIS INTERFACE IS GUARANTEED TO CHANGE.
This will be to better accommodate memory allocation for call contexts.
.Pp
These function provide a way to communicate with the kernel.
They provide data storage and buffering.
There are two classes of request-handling functions:
the get-family works with requests incoming from the kernel and
the put-family is involved with storing the results and communicating
them back to the kernel.
.Pp
Data strorage for a get request is allocated with
.Fn puffs_req_makeget .
It will allocate
.Fa buflen
bytes of memory and set the maximum number of operations to be queried
from the kernel to
.Fa maxops .
A value of 0 means that the maximum number of opearations is limited by
buffer space and number of available incoming operations.
The maximum number can later be altered using
.Fn puffs_req_setmaxget .
.Pp
Operations are queried from the kernel into the buffer
.Fa pgr
by using
.Fn puffs_req_loadget .
The number of requests returned has an upper limit given by the
.Va maxops
associated with
.Fa pgr ,
but this might return fewer requests if there was not enough space
in the buffer or if fewer requests were available at the time of
the call.
In case at least one request is returned, the operation
is considered to be succesful.
The function also resets any previous state in the buffer back to
what it would have been like immediate after the call to
.Fn puffs_req_makeget
prior to loading the new operations.
.Pp
After the request structure has been filled by
.Fn puffs_req_loadget ,
individual requests can be queried for with
.Fn puffs_req_get .
The best way to handle one is to pass it to
.Fn puffs_dopreq ,
which will decode the request, create a callcontext (cc), and call
the appropriate file system operation.
The number of requests remaining available for get is given by
.Fn puffs_req_remainingget .
.Pp
Resources associated with a request buffer are freed using
.Fn puffs_req_destroyget .
After this call the handle is invalid.
.Pp
Conversely,
.Fn puffs_req_makeput
creates a request buffer for storing information processed by the file
system and waiting delivery to the kernel.
.Pp
The functions
.Fn puffs_req_put
and
.Fn puffs_req_putcc
are queue up information from completed calls.
In case the request was handled by the framework, the latter should be used.
If it was manually decoded and a callcontext was never created, the former
can be used.
In almost all cases the proper method is to use the latter.
Note that only those operations which desire a reply should get
queued.
This can be tested by invoking
.Fn PUFFSOP_WANTREPLY
on the operation class found in
.Fa preq_opclass .
.Pp
The results will be fed to the kernel using
.Fn puffs_req_putput .
.Pp
The buffer is reset to a pristine state with
.Fn puffs_req_resetput .
Notice the dissymmetry with the get-case, where the buffer is
reset automatically.
.Pp
Resources allocated with the put-buffer are released using
.Fn puffs_req_destroyput
.Pp
To automatically handle a get-process cycle, a file system can opt to use
.Fn puffs_req_handle ,
which will fetch
.Fa maxops
operations from the kernel and process them.
The caller should them proceed to possibly add more results, perhaps
as a result of continuations which were able to finish, and then
call
.Fn puffs_req_putput
in the usual manner.
.Pp
The call
.Fn puffs_dopreq
processes the given request
.Fa preq
and stores the possible return value in
.Fa ppr .
It should be noted that this call might not return a result in case
the operation it calls decides to block with
.Fn puffs_cc_yield .
.Sh RETURN VALUES
These function return a valid pointer on success or
.Dv NULL
on failure.
Functions which return an integer will return \-1 on failure.
All failing calls will indicate the error by setting
.Va errno .
.Sh SEE ALSO
.Xr puffs 3 ,
.Xr puffs_cc 3