diff options
Diffstat (limited to 'doc/src/manual/gun.await.asciidoc')
-rw-r--r-- | doc/src/manual/gun.await.asciidoc | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/doc/src/manual/gun.await.asciidoc b/doc/src/manual/gun.await.asciidoc new file mode 100644 index 0000000..b96d643 --- /dev/null +++ b/doc/src/manual/gun.await.asciidoc @@ -0,0 +1,114 @@ += gun:await(3) + +== Name + +gun:await - Wait for a response + +== Description + +[source,erlang] +---- +await(ConnPid, StreamRef) + -> await(ConnPid, StreamRef, 5000, MonitorRef) + +await(ConnPid, StreamRef, MonitorRef) + -> await(ConnPid, StreamRef, 5000, MonitorRef) + +await(ConnPid, StreamRef, Timeout) + -> await(ConnPid, StreamRef, Timeout, MonitorRef) + +await(ConnPid, StreamRef, Timeout, MonitorRef) + -> Result + +ConnPid :: pid() +StreamRef :: reference() +MonitorRef :: reference() +Timeout :: timeout() +Result :: tuple() - see below +---- + +Wait for a response. + +This function waits for a message from the given stream and +returns it as a tuple. An error will be returned should the +process fail or a relevant message is not received within +the specified duration. + +== Arguments + +ConnPid:: + +The pid of the Gun connection process. + +StreamRef:: + +Identifier of the stream for the original request. + +Timeout:: + +How long to wait for a message, in milliseconds. + +MonitorRef:: + +Monitor for the Gun connection process. ++ +A monitor is automatically created for the duration of this +call when one is not provided. + +== Return value + +A number of different tuples can be returned. They correspond +to the message of the same name and they contain the same +elements minus the pid and stream reference. Error tuples +may also be returned when a timeout or an error occur. + +[source,erlang] +---- +Result :: {inform, Status, Headers} + {response, IsFin, Status, Headers} + {data, IsFin, Data} + {trailers, Trailers} + {push, NewStreamRef, Method, URI, Headers} + {error, Reason} + +Reason :: timeout | any() +---- + +Because the messages and returned tuples are equivalent, +please refer to the manual pages for each message for +further information: + +* link:man:gun_push(3)[gun_push(3)] - Server-initiated push +* link:man:gun_inform(3)[gun_inform(3)] - Informational response +* link:man:gun_response(3)[gun_response(3)] - Response +* link:man:gun_data(3)[gun_data(3)] - Response body +* link:man:gun_trailers(3)[gun_trailers(3)] - Response trailers + +== Changelog + +* *1.0*: Function introduced. + +== Examples + +.Wait for a response +[source,erlang] +---- +StreamRef = gun:get(ConnPid, "/articles", [ + {<<"accept">>, <<"text/html;q=1.0, application/xml;q=0.1">>} +]). +{response, nofin, 200, _Headers} = gun:await(ConnPid, StreamRef). +{data, fin, <<"Hello world!">>} = gun:await(ConnPid, StreamRef). +---- + +== See also + +link:man:gun(3)[gun(3)], +link:man:gun:get(3)[gun:get(3)], +link:man:gun:head(3)[gun:head(3)], +link:man:gun:options(3)[gun:options(3)], +link:man:gun:patch(3)[gun:patch(3)], +link:man:gun:post(3)[gun:post(3)], +link:man:gun:put(3)[gun:put(3)], +link:man:gun:delete(3)[gun:delete(3)], +link:man:gun:request(3)[gun:request(3)], +link:man:gun:await_body(3)[gun:await_body(3)] |