Return to puffs_cc.3 CVS log

Up to [cvs.NetBSD.org] / src / lib / libpuffs

Annotation of src/lib/libpuffs/puffs_cc.3, Revision 1.6.4.2

1.6.4.2 ! matt        1: .\"    $NetBSD$
1.1       pooka       2: .\"
                      3: .\" Copyright (c) 2007 Antti Kantee.  All rights reserved.
                      4: .\"
                      5: .\" Redistribution and use in source and binary forms, with or without
                      6: .\" modification, are permitted provided that the following conditions
                      7: .\" are met:
                      8: .\" 1. Redistributions of source code must retain the above copyright
                      9: .\"    notice, this list of conditions and the following disclaimer.
                     10: .\" 2. Redistributions in binary form must reproduce the above copyright
                     11: .\"    notice, this list of conditions and the following disclaimer in the
                     12: .\"    documentation and/or other materials provided with the distribution.
                     13: .\"
                     14: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
                     15: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     16: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     17: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
                     18: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     19: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     20: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     21: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     22: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     23: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     24: .\" SUCH DAMAGE.
                     25: .\"
1.6.4.2 ! matt       26: .Dd December 15, 2007
1.1       pooka      27: .Dt PUFFS_CC 3
                     28: .Os
                     29: .Sh NAME
                     30: .Nm puffs_cc
                     31: .Nd puffs continuation routines
                     32: .Sh LIBRARY
                     33: .Lb libpuffs
                     34: .Sh SYNOPSIS
                     35: .In puffs.h
                     36: .Ft void
1.3       pooka      37: .Fn puffs_cc_yield "struct puffs_cc *pcc"
1.1       pooka      38: .Ft void
1.3       pooka      39: .Fn puffs_cc_continue "struct puffs_cc *pcc"
1.6.4.1   matt       40: .Ft void
                     41: .Fn puffs_cc_schedule "struct puffs_cc *pcc"
1.6.4.2 ! matt       42: .Ft struct puffs_cc *
        !            43: .Fn puffs_cc_getcc "struct puffs_usermount *pu"
        !            44: .Ft void *
        !            45: .Fn puffs_docc "void *arg"
1.1       pooka      46: .Sh DESCRIPTION
                     47: .Em IMPORTANT NOTE!
                     48: This document describes interfaces which are not yet guaranteed to be
                     49: stable.
                     50: In case you update your system sources, please recompile everything
1.6.4.2 ! matt       51: and fix compilation errors.
1.1       pooka      52: If your sources are out-of-sync, incorrect operation may result.
                     53: The interfaces in this document will most likely be hugely simplified
                     54: in later versions or made transparent to the implementation.
                     55: .Pp
1.6.4.2 ! matt       56: These routines are used for the cooperative multitasking suite present
        !            57: in puffs.
1.1       pooka      58: .Pp
1.5       pooka      59: .Bl -tag -width xxxx
                     60: .It Fn puffs_cc_yield "pcc"
                     61: Suspend and save the current execution context and return control
1.1       pooka      62: to the previous point.
1.5       pooka      63: In practice, from the file system author perspective, control returns
                     64: back to where either
1.6.4.2 ! matt       65: .Fn puffs_dopufbuf
1.5       pooka      66: or
                     67: .Fn puffs_docc
                     68: was called.
                     69: .It Fn puffs_cc_continue pcc
                     70: Will suspend current execution and return control to where it was
                     71: before before calling
1.1       pooka      72: .Fn puffs_cc_yield .
1.6.4.2 ! matt       73: This is rarely called directly but rather through
        !            74: .Fn puffs_docc .
1.6.4.1   matt       75: .It Fn puffs_cc_schedule "pcc"
                     76: Schedule a continuation.
                     77: As opposed to
                     78: .Fn puffs_cc_continue
                     79: this call returns immediately.
                     80: .Fa pcc
                     81: will be scheduled sometime in the future.
1.6.4.2 ! matt       82: .It Fn puffs_cc_getcc "pu"
        !            83: Returns the current pcc or
        !            84: .Dv NULL
        !            85: if this is the main thread.
        !            86: .Em NOTE:
        !            87: The argument
        !            88: .Ar pu
        !            89: will most likely disappear at some point.
        !            90: .It Fn puffs_docc "arg"
1.5       pooka      91: Continues request suspended with
                     92: .Fn puffs_cc_yield .
1.6.4.2 ! matt       93: If the request completes without yielding again, the result is put
        !            94: into the file server response queue.
        !            95: .Pp
        !            96: The argument must be of type
        !            97: .Vt "struct puffs_cc *" .
        !            98: The return value is ignored.
        !            99: The signature of this function is intended to match
        !           100: .Fn start_routine
        !           101: of
        !           102: .Fn pthread_create .
1.5       pooka     103: .El
1.1       pooka     104: .Pp
                    105: Before calling
                    106: .Fn puffs_cc_yield
                    107: a file system will typically want to record some cookie value into its
                    108: own internal bookkeeping.
                    109: This cookie should be hooked to the
                    110: .Va pcc
                    111: so that the correct continuation can be continued when the event it
1.6.4.2 ! matt      112: was waiting for triggers.  Alternatively, the
        !           113: .Xr puffs_framebuf 3
        !           114: framework can be used for handling this automatically.
1.1       pooka     115: .Sh SEE ALSO
1.2       wiz       116: .Xr puffs 3 ,
1.6.4.2 ! matt      117: .Xr puffs_framebuf 3