From 5fe1be70078d7970c9e3bb687294d438918d7925 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 17 Jan 2024 12:52:45 +0100 Subject: Add missing manual pages for cowboy_stream functions --- doc/src/manual/cowboy_stream.asciidoc | 2 +- doc/src/manual/cowboy_stream.data.asciidoc | 81 +++++++++++++++++++++++ doc/src/manual/cowboy_stream.early_error.asciidoc | 73 ++++++++++++++++++++ doc/src/manual/cowboy_stream.info.asciidoc | 77 +++++++++++++++++++++ doc/src/manual/cowboy_stream.init.asciidoc | 80 ++++++++++++++++++++++ doc/src/manual/cowboy_stream.terminate.asciidoc | 61 +++++++++++++++++ 6 files changed, 373 insertions(+), 1 deletion(-) create mode 100644 doc/src/manual/cowboy_stream.data.asciidoc create mode 100644 doc/src/manual/cowboy_stream.early_error.asciidoc create mode 100644 doc/src/manual/cowboy_stream.info.asciidoc create mode 100644 doc/src/manual/cowboy_stream.init.asciidoc create mode 100644 doc/src/manual/cowboy_stream.terminate.asciidoc (limited to 'doc') diff --git a/doc/src/manual/cowboy_stream.asciidoc b/doc/src/manual/cowboy_stream.asciidoc index bdc56f2..25a9cf9 100644 --- a/doc/src/manual/cowboy_stream.asciidoc +++ b/doc/src/manual/cowboy_stream.asciidoc @@ -344,7 +344,7 @@ fin() :: fin | nofin ---- Used in commands and events to indicate that this is -the end of the stream. +the end of a direction of a stream. === partial_req() diff --git a/doc/src/manual/cowboy_stream.data.asciidoc b/doc/src/manual/cowboy_stream.data.asciidoc new file mode 100644 index 0000000..a0328f6 --- /dev/null +++ b/doc/src/manual/cowboy_stream.data.asciidoc @@ -0,0 +1,81 @@ += cowboy_stream:data(3) + +== Name + +cowboy_stream:data - Handle data for a stream + +== Description + +[source,erlang] +---- +data(StreamID, IsFin, Data, State) -> {Commands, State} + +StreamID :: cowboy_stream:stream_id() +IsFin :: cowboy_stream:fin() +Data :: binary() +Commands :: cowboy_stream:commands() +State - opaque +---- + +Handle data for a stream. + +This function should be called by all stream handlers. It will +propagate data to the next configured stream handler. Handlers +do not have to propagate data that has been fully handled. + +== Arguments + +StreamID:: + +The stream ID. + +IsFin:: + +Whether this is the end of the request body. + +Data:: + +The data received. + +Commands:: + +The commands to be executed. + +State:: + +The state for the next stream handler. + +== Return value + +A list of commands and an opaque state is returned. + +The list of commands returned should be included in the +commands returned from the current stream handler. It +can be modified if necessary. + +The state should be stored in the current stream +handler's state and passed to `cowboy_stream` when +necessary. The state should be treated as opaque. + +== Changelog + +* *2.0*: Function introduced. + +== Examples + +.Propagate data to the next stream handler +[source,erlang] +---- +data(StreamID, IsFin, Data, State=#state{next=Next0}) -> + MyCommands = my_commands(), + {Commands, Next} = cowboy_stream:data(StreamID, IsFin, Data, Next0), + {MyCommands ++ Commands, #state{next=Next}}. +---- + +== See also + +link:man:cowboy_stream(3)[cowboy_stream(3)], +link:man:cowboy_stream:init(3)[cowboy_stream:init(3)], +link:man:cowboy_stream:info(3)[cowboy_stream:info(3)], +link:man:cowboy_stream:terminate(3)[cowboy_stream:terminate(3)], +link:man:cowboy_stream:early_error(3)[cowboy_stream:early_error(3)] diff --git a/doc/src/manual/cowboy_stream.early_error.asciidoc b/doc/src/manual/cowboy_stream.early_error.asciidoc new file mode 100644 index 0000000..ad1d6bf --- /dev/null +++ b/doc/src/manual/cowboy_stream.early_error.asciidoc @@ -0,0 +1,73 @@ += cowboy_stream:early_error(3) + +== Name + +cowboy_stream:early_error - Handle an early error for a stream + +== Description + +[source,erlang] +---- +early_error(StreamID, Reason, PartialReq, Resp, Opts) -> Resp + +StreamID :: cowboy_stream:stream_id() +Reason :: cowboy_stream:reason() +PartialReq :: cowboy_stream:partial_req() +Resp :: cowboy_stream:resp_command() +Opts :: cowboy:opts() +---- + +Handle an early error for a stream. + +This function should be called by all stream handlers. It will +propagate the early error to the next configured stream handler. + +== Arguments + +StreamID:: + +The stream ID. + +Reason:: + +Reason for termination. + +PartialReq:: + +The request data that has been received so far. + +Resp:: + +The response that will be sent as a result of the early error. ++ +It may be modified by the stream handler before or after +being propagated to the next handler. + +Opts:: + +The protocol options. + +== Return value + +The response to be sent as a result of the early error. + +== Changelog + +* *2.0*: Function introduced. + +== Examples + +.Propagate the early error to the next stream handler +[source,erlang] +---- +early_error(StreamID, Reason, PartialReq, Resp, Opts) -> + cowboy_stream:early_error(StreamID, Reason, PartialReq, Resp, Opts). +---- + +== See also + +link:man:cowboy_stream(3)[cowboy_stream(3)], +link:man:cowboy_stream:init(3)[cowboy_stream:init(3)], +link:man:cowboy_stream:data(3)[cowboy_stream:data(3)], +link:man:cowboy_stream:info(3)[cowboy_stream:info(3)], +link:man:cowboy_stream:terminate(3)[cowboy_stream:terminate(3)] diff --git a/doc/src/manual/cowboy_stream.info.asciidoc b/doc/src/manual/cowboy_stream.info.asciidoc new file mode 100644 index 0000000..32cbd85 --- /dev/null +++ b/doc/src/manual/cowboy_stream.info.asciidoc @@ -0,0 +1,77 @@ += cowboy_stream:info(3) + +== Name + +cowboy_stream:info - Handle a message for a stream + +== Description + +[source,erlang] +---- +info(StreamID, Info, State) -> {Commands, State} + +StreamID :: cowboy_stream:stream_id() +Info :: any() +Commands :: cowboy_stream:commands() +State - opaque +---- + +Handle a message for a stream. + +This function should be called by all stream handlers. It will +propagate the event to the next configured stream handler. +Handlers do not have to propagate events that have been +fully handled. + +== Arguments + +StreamID:: + +The stream ID. + +Info:: + +The event received. + +Commands:: + +The commands to be executed. + +State:: + +The state for the next stream handler. + +== Return value + +A list of commands and an opaque state is returned. + +The list of commands returned should be included in the +commands returned from the current stream handler. It +can be modified if necessary. + +The state should be stored in the current stream +handler's state and passed to `cowboy_stream` when +necessary. The state should be treated as opaque. + +== Changelog + +* *2.0*: Function introduced. + +== Examples + +.Propagate an event to the next stream handler +[source,erlang] +---- +info(StreamID, Info, State=#state{next=Next0}) -> + MyCommands = my_commands(), + {Commands, Next} = cowboy_stream:info(StreamID, Info, Next0), + {MyCommands ++ Commands, #state{next=Next}}. +---- + +== See also + +link:man:cowboy_stream(3)[cowboy_stream(3)], +link:man:cowboy_stream:init(3)[cowboy_stream:init(3)], +link:man:cowboy_stream:data(3)[cowboy_stream:data(3)], +link:man:cowboy_stream:terminate(3)[cowboy_stream:terminate(3)], +link:man:cowboy_stream:early_error(3)[cowboy_stream:early_error(3)] diff --git a/doc/src/manual/cowboy_stream.init.asciidoc b/doc/src/manual/cowboy_stream.init.asciidoc new file mode 100644 index 0000000..addf9bc --- /dev/null +++ b/doc/src/manual/cowboy_stream.init.asciidoc @@ -0,0 +1,80 @@ += cowboy_stream:init(3) + +== Name + +cowboy_stream:init - Initialize a stream + +== Description + +[source,erlang] +---- +init(StreamID, Req, Opts) -> {Commands, State} + +StreamID :: cowboy_stream:stream_id() +Req :: cowboy_req:req() +Opts :: cowboy:opts() +Commands :: cowboy_stream:commands() +State - opaque +---- + +Initialize a stream. + +This function must be called by all stream handlers. It will +initialize the next configured stream handler. + +== Arguments + +StreamID:: + +The stream ID. + +Req:: + +The Req object. + +Opts:: + +The protocol options. + +Commands:: + +The commands to be executed. + +State:: + +The state for the next stream handler. + +== Return value + +A list of commands and an opaque state is returned. + +The list of commands returned should be included in the +commands returned from the current stream handler. It +can be modified if necessary. + +The state should be stored in the current stream +handler's state and passed to `cowboy_stream` when +necessary. The state should be treated as opaque. + +== Changelog + +* *2.0*: Function introduced. + +== Examples + +.Initialize the next stream handler +[source,erlang] +---- +init(StreamID, Req, Opts) -> + MyCommands = my_commands(), + {Commands, Next} = cowboy_stream:init(StreamID, Req, Opts), + {MyCommands ++ Commands, #state{next=Next}}. +---- + +== See also + +link:man:cowboy_stream(3)[cowboy_stream(3)], +link:man:cowboy_stream:data(3)[cowboy_stream:data(3)], +link:man:cowboy_stream:info(3)[cowboy_stream:info(3)], +link:man:cowboy_stream:terminate(3)[cowboy_stream:terminate(3)], +link:man:cowboy_stream:early_error(3)[cowboy_stream:early_error(3)] diff --git a/doc/src/manual/cowboy_stream.terminate.asciidoc b/doc/src/manual/cowboy_stream.terminate.asciidoc new file mode 100644 index 0000000..8393801 --- /dev/null +++ b/doc/src/manual/cowboy_stream.terminate.asciidoc @@ -0,0 +1,61 @@ += cowboy_stream:terminate(3) + +== Name + +cowboy_stream:terminate - Terminate a stream + +== Description + +[source,erlang] +---- +terminate(StreamID, Reason, State) -> ok + +StreamID :: cowboy_stream:stream_id() +Reason :: cowboy_stream:reason() +State - opaque +---- + +Terminate a stream. + +This function must be called by all stream handlers. It will +terminate the next configured stream handler. + +== Arguments + +StreamID:: + +The stream ID. + +Reason:: + +Reason for termination. + +State:: + +The state for the next stream handler. + +== Return value + +The atom `ok` is always returned. It can be safely ignored. + +== Changelog + +* *2.0*: Function introduced. + +== Examples + +.Terminate the next stream handler +[source,erlang] +---- +terminate(StreamID, Reason, State=#state{next=Next0}) -> + my_termination(State), + cowboy_stream:terminate(StreamID, Reason, Next0). +---- + +== See also + +link:man:cowboy_stream(3)[cowboy_stream(3)], +link:man:cowboy_stream:init(3)[cowboy_stream:init(3)], +link:man:cowboy_stream:data(3)[cowboy_stream:data(3)], +link:man:cowboy_stream:info(3)[cowboy_stream:info(3)], +link:man:cowboy_stream:early_error(3)[cowboy_stream:early_error(3)] -- cgit v1.2.3