TITLE ^

Stream::Sub - a PIR sub as source for a Stream

VERSION ^

version 0.1

SYNOPSIS ^

    # create the stream
    find_type $I0, "Stream::Sub"
    new stream, $I0

    # set the source sub
    .const .Sub temp = "_test"
    stream."source"( temp )

    ...

    .sub _test :method
        self."write"( "hello, world" )
    .end

DESCRIPTION ^

Like every stream, Stream::Sub as has a read method. The benefit is that this stream also has a write method, though it can not be called from arbitrary locations.

You have to provide a Sub PMC that gets called when you call read for the first time. This sub gets the stream passed in as P2 ("self" if you declare it as a method). You can pass it to other functions if you want. Arguments passed to read on its first invokation are forwarded to the sub you provide. This invokation looks like a method call, but it isn't one from a technical point of view.

This special "method" can call write, which will internally create a Continuation to return to the current execution point when read is called the next time. The read method creates a continuation before invoking the provided sub or the continuation captured by the write method. read's continuation is used to return the string parameter passed to write as the return value of the read method. The parameters passed to read will be the return values of write().

So, if you call the read method, a part of the provided sub will be run, until it calls the write method. At this point, the original program execution will continue, until you call the read method again, which will run the next part of your sub.

The stream will be disconnected automatically if the provided sub returns.

METHODS ^

source."write"()

...

source."rawRead"() (internal)

...

AUTHOR ^

Jens Rieks <parrot at jensbeimsurfen dot de> is the author and maintainer. Please send patches and suggestions to the Perl 6 Internals mailing list.

COPYRIGHT ^

Copyright (C) 2004-2006, The Perl Foundation.


parrot