version 1.9, 2007/12/07 14:55:12 |
version 1.10, 2007/12/15 20:08:06 |
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
.\" SUCH DAMAGE. |
.\" SUCH DAMAGE. |
.\" |
.\" |
.Dd December 7, 2007 |
.Dd December 15, 2007 |
.Dt PUFFS_CC 3 |
.Dt PUFFS_CC 3 |
.Os |
.Os |
.Sh NAME |
.Sh NAME |
|
|
.Fn puffs_cc_continue "struct puffs_cc *pcc" |
.Fn puffs_cc_continue "struct puffs_cc *pcc" |
.Ft void |
.Ft void |
.Fn puffs_cc_schedule "struct puffs_cc *pcc" |
.Fn puffs_cc_schedule "struct puffs_cc *pcc" |
|
.Ft struct puffs_cc * |
|
.Fn puffs_cc_getcc "struct puffs_usermount *pu" |
|
.Ft void * |
|
.Fn puffs_docc "void *arg" |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
.Em IMPORTANT NOTE! |
.Em IMPORTANT NOTE! |
This document describes interfaces which are not yet guaranteed to be |
This document describes interfaces which are not yet guaranteed to be |
Line 49 If your sources are out-of-sync, incorre |
|
Line 53 If your sources are out-of-sync, incorre |
|
The interfaces in this document will most likely be hugely simplified |
The interfaces in this document will most likely be hugely simplified |
in later versions or made transparent to the implementation. |
in later versions or made transparent to the implementation. |
.Pp |
.Pp |
These functions enable the use of continuations within the framework. |
These routines are used for the cooperative multitasking suite present |
Every operation callback within a file system implementation is |
in puffs. |
automatically passed an opaque cookie, |
|
.Va pcc , |
|
to be used as a continuation handle. |
|
.Pp |
|
File systems using continuations should define their own event loop |
|
instead of using |
|
.Fn puffs_mainloop . |
|
.Pp |
.Pp |
.Bl -tag -width xxxx |
.Bl -tag -width xxxx |
.It Fn puffs_cc_getusermount "pcc" |
|
Returns a pointer to the file system structure |
|
.Va struct puffs_usermount |
|
the context is associated with. |
|
.It Fn puffs_cc_getspecific "pcc" |
|
Returns a pointer to file system private data. |
|
This is shorthand for |
|
calling |
|
.Fn puffs_getspecific |
|
with the result from |
|
.Fn puffs_cc_getusermount . |
|
.It Fn puffs_cc_yield "pcc" |
.It Fn puffs_cc_yield "pcc" |
Suspend and save the current execution context and return control |
Suspend and save the current execution context and return control |
to the previous point. |
to the previous point. |
In practice, from the file system author perspective, control returns |
In practice, from the file system author perspective, control returns |
back to where either |
back to where either |
.Fn puffs_req_handle |
.Fn puffs_dopufbuf |
or |
or |
.Fn puffs_docc |
.Fn puffs_docc |
was called. |
was called. |
|
|
Will suspend current execution and return control to where it was |
Will suspend current execution and return control to where it was |
before before calling |
before before calling |
.Fn puffs_cc_yield . |
.Fn puffs_cc_yield . |
This is rarely called directly. |
This is rarely called directly but rather through |
|
.Fn puffs_docc . |
.It Fn puffs_cc_schedule "pcc" |
.It Fn puffs_cc_schedule "pcc" |
Schedule a continuation. |
Schedule a continuation. |
As opposed to |
As opposed to |
|
|
this call returns immediately. |
this call returns immediately. |
.Fa pcc |
.Fa pcc |
will be scheduled sometime in the future. |
will be scheduled sometime in the future. |
.It Fn puffs_docc "pcc" "ppr" |
.It Fn puffs_cc_getcc "pu" |
|
Returns the current pcc or |
|
.Dv NULL |
|
if this is the main thread. |
|
.Em NOTE: |
|
The argument |
|
.Ar pu |
|
will most likely disappear at some point. |
|
.It Fn puffs_docc "arg" |
Continues request suspended with |
Continues request suspended with |
.Fn puffs_cc_yield . |
.Fn puffs_cc_yield . |
If the request completes without yielding again, the result can be |
If the request completes without yielding again, the result is put |
found from |
into the file server response queue. |
.Fa ppr . |
.Pp |
|
The argument must be of type |
|
.Vt "struct puffs_cc *" . |
|
The return value is ignored. |
|
The signature of this function is intended to match |
|
.Fn start_routine |
|
of |
|
.Fn pthread_create . |
.El |
.El |
.Pp |
.Pp |
Before calling |
Before calling |
Line 107 own internal bookkeeping. |
|
Line 109 own internal bookkeeping. |
|
This cookie should be hooked to the |
This cookie should be hooked to the |
.Va pcc |
.Va pcc |
so that the correct continuation can be continued when the event it |
so that the correct continuation can be continued when the event it |
was waiting for triggers. |
was waiting for triggers. Alternatively, the |
.Pp |
.Xr puffs_framebuf 3 |
The puffs ssh file system is supposed to be the canonical example |
framework can be used for handling this automatically. |
for the use of the continuation framework. |
|
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr puffs 3 , |
.Xr puffs 3 , |
.Xr puffs_framebuf 3 , |
.Xr puffs_framebuf 3 |
.Xr puffs_req 3 , |
|
.Xr mount_psshfs 8 |
|