stream.yaws

<erl>


box(Str) ->
    {'div',[{class,"box"}],
     {pre,[],yaws_api:htmlize(Str)}}.

tbox(T) ->
    box(lists:flatten(io_lib:format("~p",[T]))).


ssi(File) ->
    {'div',[{class,"box"}],
     {pre,[],
      {ssi, File,[],[]}}}.


out(A) ->
    [{ssi, "TAB.inc", "%%",[{"stream", "choosen"}]},
     {ehtml,
     {'div',[{id, "entry"}],
      [{h1, [], "Streaming data to the client"},

       {p, [],
        "Sometimes we want to stream data to the client. Maybe we don't know or cannot compute the size of the data. Regardless of the reason, we do not want to keep all data in memory until it's shipped to the client. We want to use chunked encodings, and simply send data in chunks to the client. This is performed in steps. First the out/1 return value:"},

       box(" {streamcontent, MimeType, FirstChunk}"),

       {p,[], ["Is returned from the out/1 function"
               " This makes the erlang process within yaws processing that particular page go into a receive loop, waiting for more data. Somehow, another process in  the erlang system must then deliver data to the waiting/receiving erlang process. There are two asynchronous API functions that can be used to deliver that data."]},

       box("yaws_api:stream_chunk_deliver(YawsPid, Data)"),
       {p, [], "and"},
       box("yaws_api:stream_chunk_end(YawsPid)"),

       {p, [], "The YawsPid argument is the process identifier of the original yaws process processing the page, i.e. self(), in the .yaws file."},

       {p, [],"Maybe this gets clear with a programming example, let's use a process reading  a random number of bytes from /dev/urandom as the source of the data"},

       ssi("urandom.yaws"),

       {p, [],
        ["The above slightly bizarre code can be executed ",
         {a, [{href, "urandom.yaws"}], "here"},
         ". The code creates a process which reads a random amount of bytes from /dev/urandom and sends them to the client, piece by piece. "]},

       {p,[], "There is also a version of the API that delivers the data in a blocking fashion. Whenever the producer of the stream is faster than the consumer, that is the WWW client, we must use a synchronous version of the code. The api function is called:"},

       box("yaws_api:stream_chunk_deliver_blocking(YawsPid, Data)"),

       {p,[],
        "For applications that want to avoid buffering data in memory but do not want chunked transfer, or for applications that employ long-polling (Comet) techniques, another streamcontent variant lets the application send data directly on the client socket. Such applications should first return the following from their out/1 function:"},

       box(" {streamcontent_from_pid, MimeType, Pid}"),

       {p,[], "where the Pid argument is the pid of the application process that will send the data, and MimeType is the MIME type of the data to be sent. When yaws is ready for Pid, it sends one of the following messages to it:"},

       {ul,[],
        [{li,[]," {ok, YawsPid} indicates to Pid that it can send data over the socket, which is available as Arg#arg.clisock. YawsPid will be used later to tell yaws that Pid has finished streaming."},
         {li,[]," {discard, YawsPid} indicates to Pid that it should avoid sending data to the socket. This is needed when the client invokes an HTTP request such as HEAD that has no response body."}]},

       {p,[],"Pid can send data on the socket by calling:"},

       box(" yaws_api:stream_process_deliver(Socket, IoList)"),

       {p,[],"where IoList is the data to be sent. For chunked transfer, Pid must call:"},

       box(" yaws_api:stream_process_deliver_chunk(Socket, IoList)"),

       {p,[],"which tells yaws to use HTTP chunked transfer to send IoList. Applications using chunked transfer in this manner must always remember to end their data transfer by calling:"},

       box(" yaws_api:stream_process_deliver_final_chunk(Socket, IoList)"),


       {p,[],"where IoList is an iolist of size 0 or more. This creates the final HTTP chunk that the client uses to detect the end of the transfer."},

       {p,[],"When Pid finishes sending data, or when it receives a {discard, YawsPid} message, it must call:"},

       box(" yaws_api:stream_process_end(Socket, YawsPid)"),

       {p,[],"This informs yaws that Pid is finished with the socket and will no longer use it directly."},

       box(" yaws_api:stream_process_end(closed, YawsPid)"),

       {p,[],"This informs yaws that Pid has not only finished with the socket, but has also closed it. Yaws will not attempt to use the socket anymore after the application calls this function."},

       {p,[],"Applications using streamcontent_from_pid should be sure to set a Content-Length header in their out/1 return value if they want to avoid chunked transfer encoding for their return value. Yaws automatically sets the HTTP Transfer-Encoding header to chunked if it doesn't detect a Content-Length header. Another alternative is to return the {header, {transfer_encoding, erase}} header from out/1 in order to disable chunked encoding."},

       {p,[],"Here's an example of using streamcontent_from_pid:"},

       ssi("urandom_from_pid.yaws"),

       {p, [],
        ["The above code can be executed ",
         {a, [{href, "urandom_from_pid.yaws"}], "Here"},
         ". The code creates a process which reads a random amount of bytes from /dev/urandom and sends them to the client via the socket. "]}

       ]}},
       {ssi, "END2",[],[]}
       ].


</erl>


</html>