view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        function inside an eval() block and use alarm() to limit the
        execution. Another example is "retry" property, implemented by
        Perinci::Sub::Property::retry which generates code to call function
        inside a simple retry loop.

    Normally you do not use PSW directly in your applications. You might
    want to check out Perinci::Access::Perl and Perinci::Exporter on
    examples of wrapping function dynamically (during runtime), or
    Dist::Zilla::Plugin::Rinci::Wrap on an example of embedding the
    generated wrapping code to source code during build.

EXTENDING
    The framework is simple and extensible. Please delve directly into the
    source code for now. Some notes:

    The internal uses OO.

    The main wrapper building mechanism is in the wrap() method.

    For each Rinci property, it will call handle_NAME() wrapper handler
    method. The handlemeta_NAME() methods are called first, to determine
    order of processing. You can supply these methods either by subclassing
    the class or, more simply, monkeypatching the method in the
    "Perinci::Sub::Wrapper" package.

    The wrapper handler method will be called with a hash argument,
    containing these keys: value (property value), new (this key will exist
    if "convert" argument of wrap() exists, to convert a property to a new
    value).

    For properties that have name in the form of "NAME1.NAME2.NAME3" (i.e.,
    dotted) only the first part of the name will be used (i.e.,
    handle_NAME1()).

VARIABLES
  $Log_Wrapper_Code (BOOL)
    Whether to log wrapper result. Default is from environment variable
    LOG_PERINCI_WRAPPER_CODE, or false. Logging is done with Log::ger at
    trace level.

RINCI FUNCTION METADATA
  x.perinci.sub.wrapper.disable_validate_args => bool
    Can be set to 1 to set "validate_args" to 0 by default. This is used
    e.g. if you already embed/insert code to validate arguments by other
    means and do not want to repeat validating arguments. E.g. used if you
    use Dist::Zilla::Plugin::Rinci::Validate.

  x.perinci.sub.wrapper.disable_validate_result => bool
    Can be set to 1 to set "validate_result" to 0 by default. This is used
    e.g. if you already embed/insert code to validate result by other means
    and do not want to repeat validating result. E.g. used if you use
    Dist::Zilla::Plugin::Rinci::Validate.

  x.perinci.sub.wrapper.logs => array
    Generated/added by this module to the function metadata for every
    wrapping done. Used to avoid adding repeated code, e.g. to validate
    result or arguments.

PERFORMANCE NOTES
    The following numbers are produced on an Intel Core i5-2400 3.1GHz
    desktop using PSW v0.51 and Perl v5.18.2. Operating system is Debian sid
    (64bit).

    For perspective, empty subroutine ("sub {}") as well as "sub { [200,
    "OK"] }" can be called around 5.3 mil/sec.

    Wrapping this subroutine "sub { [200, "OK"] }" and this simple metadata
    "{v=>1.1}" using default options yields call performance for $sub->() of
    about 0.9 mil/sec. With "validate_args=>0" and "validate_result=>0",
    it's 1.5 mil/sec.

    As more (and more complex) arguments are introduced and validated,
    overhead will increase. The significant portion of the overhead is in
    argument validation. For example, this metadata "{v=>1.1,
    args=>{a=>{schema=>"int"}}}" yields 0.5 mil/sec.

FUNCTIONS
  wrap_sub
    Usage:

     wrap_sub(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Wrap subroutine to do various things, like enforcing Rinci properties.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   compile => *bool* (default: 1)

        Whether to compile the generated wrapper.

        Can be set to 0 to not actually wrap but just return the generated
        wrapper source code.

    *   convert => *hash*

        Properties to convert to new value.

        Not all properties can be converted, but these are a partial list of
        those that can: v (usually do not need to be specified when
        converting from 1.0 to 1.1, will be done automatically), args_as,
        result_naked, default_lang.

    *   core => *bool*

        If set to true, will avoid the use of non-core modules.

    *   core_or_pp => *bool*

        If set to true, will avoid the use of non-core XS modules.

        In other words, will stick to core or pure-perl modules only.

    *   debug => *bool* (default: 0)

        Generate code with debugging.

        If turned on, will produce various debugging in the generated code.
        Currently what this does: