Overview.htm
author Takeshi Yoshino <tyoshino@google.com>
Fri, 10 Jan 2014 20:00:02 +0900
changeset 125 98448480356b
parent 124 9dc273a030cc
child 126 be34c357de7f
permissions -rw-r--r--
ByteStreamReadType -> StreamReadType
38
3cdd8b2d21d9 Merging changes made for preparing WD
Takeshi Yoshino <tyoshino@google.com>
parents: 37
diff changeset
     1
<!DOCTYPE html>
8
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
     2
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
     3
<html>
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
     4
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
     5
<head>
83
afed6501a898 moved images, fixed typos, fixed header
fmoussa <feras.moussa@hotmail.com>
parents: 81
diff changeset
     6
	<title>Streams API</title>
11
f99aafc91a32 First complete update to prep for FPWD
fmoussa <feras.moussa@hotmail.com>
parents: 10
diff changeset
     7
	<meta content="text/html;charset=utf-8" http-equiv="Content-Type">
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
     8
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
     9
	<!-- <script class=remove src="http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js"></script> -->
10
bbfec9730bc4 Resolving respec js file path
fmoussa <feras.moussa@hotmail.com>
parents: 8
diff changeset
    10
	<script class="remove" src="https://www.w3.org/Tools/respec/respec-w3c-common"></script>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    11
	<!-- <script class="remove" src="respec-w3c-common.js"></script> -->
8
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
    12
10
bbfec9730bc4 Resolving respec js file path
fmoussa <feras.moussa@hotmail.com>
parents: 8
diff changeset
    13
	<script class="remove">
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    14
var respecConfig = {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    15
	// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    16
	specStatus:           "ED",
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
    17
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    18
	// the specification's short name, as in http://www.w3.org/TR/short-name/
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    19
	shortName:            "streams-api",
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
    20
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    21
	// if your specification has a subtitle that goes below the main
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    22
	// formal title, define it here
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    23
	// subtitle   :  "an excellent document",
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
    24
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    25
	// if you wish the publication date to be other than today, set this
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    26
	// publishDate:  "yyyy-mm-dd",
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
    27
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    28
	// if the specification's copyright date is a range of years, specify
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    29
	// the start date here:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    30
	// copyrightStart: "2005"
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    31
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    32
	// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    33
	// and its maturity status
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    34
	// previousPublishDate:  "yyyy-mm-dd",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    35
	// previousMaturity:  "WD",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    36
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    37
	// if there a publicly available Editor's Draft, this is the link
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    38
	edDraftURI:           "http://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    39
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    40
	// if this is a LCWD, uncomment and set the end of its review period
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    41
	// lcEnd: "2009-08-05",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    42
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    43
	// if you want to have extra CSS, append them to this list
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    44
	// it is recommended that the respec.css stylesheet be kept
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    45
	//extraCSS:             ["http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    46
	//	"http://www.w3.org/StyleSheets/TR/W3C-ED.css",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    47
	//	],
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    48
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    49
	// editors, add as many as you like
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    50
	// only "name" is required
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    51
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    52
	localBiblio: {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    53
		"EncodingDetermination": {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    54
			title: "Encoding",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    55
			href: "http://encoding.spec.whatwg.org/",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    56
			authors: ["Anne van Kesteren", "Joshua Bell"],
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    57
			publisher: "WHATWG"
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    58
		}
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    59
	},
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    60
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    61
	editors:  [
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    62
		{ name: "Feras Moussa", url: "mailto:feras.moussa@hotmail.com",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    63
			company: "Invited Expert",  },
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    64
		{ name: "Takeshi Yoshino", url: "mailto:tyoshino@google.com",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    65
			company: "Google, Inc.",  },
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    66
	],
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    67
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    68
	// authors, add as many as you like.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    69
	// This is optional, uncomment if you have authors as well as editors.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    70
	// only "name" is required. Same format as editors.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    71
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    72
	//authors:  [
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    73
	//    { name: "Your Name", url: "http://example.org/",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    74
	//      company: "Your Company", companyURL: "http://example.com/" },
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    75
	//],
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    77
	// name of the WG
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    78
	wg:           "W3C Web Applications (WebApps)",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    79
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    80
	// URI of the public WG page
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    81
	wgURI:        "http://www.w3.org/2008/webapps/",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    82
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    83
	// name (with the @w3c.org) of the public mailing to which comments are due
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    84
	wgPublicList: "public-webapps",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    85
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    86
	// URI of the patent status for this WG, for Rec-track documents
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    87
	// !!!! IMPORTANT !!!!
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    88
	// This is important for Rec-track documents, do not copy a patent URI from a random
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    89
	// document unless you know what you're doing. If in doubt ask your friendly neighbourhood
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    90
	// Team Contact.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    91
	wgPatentURI:  "",
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    92
};
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    93
</script>
8
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
    94
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
    95
	<!-- Styles to mimic File API spec -->
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    96
	<!-- <style type="text/css"> -->
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    97
	<!-- 	table.error { border-collapse:collapse; border-style:hidden hidden none hidden } -->
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    98
	<!-- 	table.error thead { border-bottom:solid } -->
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
    99
	<!-- 	table.error tbody th:first-child { border-left:solid } -->
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   100
	<!-- 	table.error td, table th { border-left:solid; border-right:solid; border-bottom:solid thin; vertical-align:top; padding:0.2em } -->
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   101
	<!-- </style> -->
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   102
7
4a496b9c9944 fixed issue with resolving css file
fmoussa <feras.moussa@hotmail.com>
parents: 6
diff changeset
   103
</head>
8
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
   104
<body>
35
1e0b2c48a167 Added sotd
fmoussa <feras.moussa@hotmail.com>
parents: 27
diff changeset
   105
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   106
	<section id="sotd">
46
d9d23bed8517 Add links to Bugzilla listing and entering UI.
Takeshi Yoshino <tyoshino@google.com>
parents: 45
diff changeset
   107
		<p>
d9d23bed8517 Add links to Bugzilla listing and entering UI.
Takeshi Yoshino <tyoshino@google.com>
parents: 45
diff changeset
   108
			This document is not complete.
d9d23bed8517 Add links to Bugzilla listing and entering UI.
Takeshi Yoshino <tyoshino@google.com>
parents: 45
diff changeset
   109
			It is subject to major changes and, while early experimentations are encouraged, it is therefore not intended for implementation.
d9d23bed8517 Add links to Bugzilla listing and entering UI.
Takeshi Yoshino <tyoshino@google.com>
parents: 45
diff changeset
   110
		</p>
d9d23bed8517 Add links to Bugzilla listing and entering UI.
Takeshi Yoshino <tyoshino@google.com>
parents: 45
diff changeset
   111
d9d23bed8517 Add links to Bugzilla listing and entering UI.
Takeshi Yoshino <tyoshino@google.com>
parents: 45
diff changeset
   112
		<p>
d9d23bed8517 Add links to Bugzilla listing and entering UI.
Takeshi Yoshino <tyoshino@google.com>
parents: 45
diff changeset
   113
			To check recent changes and rationale for them, please visit <a href="https://dvcs.w3.org/hg/streams-api/">Mercurial history</a>.
d9d23bed8517 Add links to Bugzilla listing and entering UI.
Takeshi Yoshino <tyoshino@google.com>
parents: 45
diff changeset
   114
			Check open bugs at Bugzilla using <a href="https://www.w3.org/Bugs/Public/buglist.cgi?component=Streams%20API">this link</a>.
d9d23bed8517 Add links to Bugzilla listing and entering UI.
Takeshi Yoshino <tyoshino@google.com>
parents: 45
diff changeset
   115
			If you wish to submit a bug, please use <a href="https://www.w3.org/Bugs/Public/enter_bug.cgi?product=WebAppsWG&component=Streams%20API">this link</a>.
d9d23bed8517 Add links to Bugzilla listing and entering UI.
Takeshi Yoshino <tyoshino@google.com>
parents: 45
diff changeset
   116
			All comments and bug reports are welcome.
d9d23bed8517 Add links to Bugzilla listing and entering UI.
Takeshi Yoshino <tyoshino@google.com>
parents: 45
diff changeset
   117
		</p>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   118
	</section>
35
1e0b2c48a167 Added sotd
fmoussa <feras.moussa@hotmail.com>
parents: 27
diff changeset
   119
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   120
	<section id="abstract">
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   121
		<p>
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   122
			This specification provides an API for representing a stream of data in web applications, as well as programmatically reading and writing it.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   123
			This includes:
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   124
		</p>
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   125
		<ul>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   126
			<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   127
				An interface named <a>WritableStream</a> which defines a general protocol for data consuming APIs (<a href="#consumers">consumers</a>) to communicate with data producing code (<a href="#producers">producers</a>).
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   128
			</li>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   129
			<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   130
				An interface named <a>ReadableStream</a> which defines a general protocol for data producing APIs to communicate with data consuming code.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   131
			</li>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   132
			<li>
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   133
				An interface named <a>ByteStream</a> which inherits both WritableStream and ReadableStream and represents a sequence of data.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   134
			</li>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   135
			<li>
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   136
				A struct type named <a>StreamReadResult</a> which represents the result of consuming operations such as <code>read()</code> and <code>pipe()</code>.
125
98448480356b ByteStreamReadType -> StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents: 124
diff changeset
   137
				It holds:
98448480356b ByteStreamReadType -> StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents: 124
diff changeset
   138
				<ul>
98448480356b ByteStreamReadType -> StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents: 124
diff changeset
   139
					<li>Chunk of content read from a <a>ReadableStream</a></li>
98448480356b ByteStreamReadType -> StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents: 124
diff changeset
   140
					<li>The total cost of the chunk</li>
98448480356b ByteStreamReadType -> StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents: 124
diff changeset
   141
					<li>EOF signal</li>
98448480356b ByteStreamReadType -> StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents: 124
diff changeset
   142
					<li>Error info</li>
98448480356b ByteStreamReadType -> StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents: 124
diff changeset
   143
				</ul>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   144
			</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   145
			<li>
125
98448480356b ByteStreamReadType -> StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents: 124
diff changeset
   146
				An enum <a>StreamReadType</a> which represents data types as which data can be read from a <a>ReadableStream</a>.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   147
			</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   148
			<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   149
				A list of notable byte stream <a href="#producers">producers</a> and <a href="#consumers">consumers</a> for which we can apply either or both of <a>ReadableStream</a> and <a>WritableStream</a> model.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   150
			</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   151
			<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   152
				Extensions to <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-xmlhttprequest-interface">XMLHttpRequest</a> [[!XMLHTTPREQUEST2]] to add support for uploading data via <a>WritableStream</a> and downloading a response as a <a>ReadableStream</a>.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   153
			</li>
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   154
			<li>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   155
				Extensions to <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-createObjectURL">URL.createObjectURL</a> and
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   156
				<a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-revokeObjectURL">URL.revokeObjectURL</a> to add support for <a>ReadableStream</a>.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   157
			</li>
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   158
		</ul>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   159
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   160
		<p>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   161
			This API is designed to be used in conjunction with other APIs and elements on the web platform, notably:
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   162
			<a href="http://dev.w3.org/2006/webapi/FileAPI">File</a> [[!FILE-API]],
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   163
			<a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2">XMLHttpRequest</a>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   164
			(e.g. with an overloaded <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-send-method"><code>send()</code></a> method
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   165
			and <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-responsetype-attribute"><code>response</code></a> object for <a>ReadableStream</a> objects) [[!XMLHTTPREQUEST2]],
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   166
			<a href="http://dev.w3.org/html5/postmsg/#dom-window-postmessage"><code>postMessage</code></a>, and
8
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
   167
			Web Workers [[!WEBWORKERS]].
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   168
		</p>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   169
	</section>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   170
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   171
	<section id="introduction" class="section informative">
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   172
		<h2>Introduction</h2>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   173
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   174
		<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   175
			Web applications should have the ability to acquire, manipulate, and pass data in a wide variety of forms, including as a sequence of data made available over time.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   176
			This specification defines the basic representation for byte streams, and programmatic ways to read and write streams of data and errors raised on those operations.
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   177
		</p>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   178
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   179
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   180
			The <a>WritableStream</a> interface defines a general protocol for <a href="#consumers">data consuming APIs</a> to communicate with data producing code.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   181
			In these cases, the data consuming API, such as a decoder, provides a <a>WritableStream</a> for other applications to write to, enabling the decoder to begin decoding data as it becomes available.
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   182
			The data is written to the internal data sink of a data consuming API using:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   183
			<ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   184
				<li>The <code>write()</code> method for writing bytes to the data sink as a <a>ArrayBufferView</a>, <a>DOMString</a> or <a>Blob</a></li>
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   185
				<li>
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   186
					The <code>awaitSpaceAvailable()</code> method for allowing a data-producer to write to the data sink only when the data sink specifies it is now available to consume more data.
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   187
					This is useful for cases where an app may want to avoid backpressure and filling the internal buffer.
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   188
				</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   189
			</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   190
			Actual transfer of bytes to the data sink may happen either synchronously or asynchronously.
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   191
			<a>WritableStream</a> hides the details of actual communication with the data sink while allowing for an efficient transfer of bytes.
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   192
		</p>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   193
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   194
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   195
			The <a>ReadableStream</a> interface defines a general protocol for <a href="#producers">data producing APIs</a> to communicate with data consuming code.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   196
			This interface represents the potential for an infinite amount of bytes which are obtained over time and read once.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   197
			Data consuming code reads data from the data source inside a data producing API using:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   198
			<ul>
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   199
				<li>The <code>read()</code> and <code>readUpTo()</code> methods for reading bytes from the data source as a <a>ArrayBufferView</a>, <a>DOMString</a> or <a>Blob</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   200
				<li>The <code>pullAmount</code> attribute to pace data retrieval from the data source</li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   201
				<li>The <code>pipe()</code> method for transferring data in bulk from the data source into the data sink of a <a>WritableStream</a> from another API</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   202
			</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   203
			Actual transfer of bytes from the data source may happen either synchronously or asynchronously.
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   204
			The <a>ReadableStream</a> hides the details of actual communication with the data source while allowing for an efficient transfer of bytes.
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   205
		</p>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   206
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   207
		<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   208
			With the combination of the following features, this interface suite responds to various simple and complex needs of byte stream handling.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   209
			<ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   210
				<li>Delayed notification of completion by using <a>Promise</a>s</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   211
				<li>Explicit back pressure management by propagating room for consumption back to producers</li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   212
				<li><a>WritableStream</a> always accepts incoming data synchronously</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   213
			</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   214
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   215
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   216
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   217
			The <a>ByteStream</a> is a simple implementation of both the <a>WritableStream</a> and <a>ReadableStream</a> interface.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   218
			A ByteStream has a single queue of bytes and it works as a data sink for the WritableStream interface and as a data source for the ReadableStream interface.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   219
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   220
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   221
		<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   222
			Read and write operations on these interfaces are implemented using <a>Promise</a>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   223
			When an operation completes, the Promise returned by a method will be fulfilled, and then the fulfill callback set to the Promise will handle the result.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   224
			Error conditions that may arise during an operation will be handled by the reject callback set to the Promise.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   225
			An example will be illustrative.
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   226
		</p>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   227
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   228
		<p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   229
			In the example below, different code blocks handle progress, error, and success conditions.
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   230
			The example demonstrates how to read a chunk of data from a <a>ReadableStream</a> using <code>read()</code>.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   231
			The <a>ReadableStream</a> may of come from a <a href="#producers">producer</a> such as <code>XMLHttpRequest</code>.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   232
			Additionally, it demonstrates how to read bytes from a <a>ReadableStream</a> until an EOF is encountered.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   233
		</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   234
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   235
		<pre class="example">
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   236
// Tell stream that we're ready to consume 1024 bytes.
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   237
stream.pullAmount = 1024;
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   238
stream.readEncoding = "UTF-8";
121
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   239
stream.readBinaryAs = "arraybuffer";
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   240
stream.read().then(
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   241
  function (result) {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   242
    // Process data
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   243
  },
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   244
  function (error) {
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   245
    // Handle error
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   246
  });</pre>
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   247
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   248
		<pre class="example">// Read data from the ReadableStream repeatedly
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   249
function readUntilEof() {
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   250
  stream.read().then(
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   251
    function (result) {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   252
      processData(result.data);
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   253
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   254
      if (!result.eof) {
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   255
        readUntilEof();
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   256
      }
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   257
    },
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   258
    function (error) {
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   259
      // Handle error
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   260
    });
8
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
   261
}
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   262
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   263
readUntilEof();</pre>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   264
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   265
		<p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   266
			In the example below, different code blocks handle progress, error, and success conditions.
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   267
			The example below demonstrates how to obtain a <a>ReadableStream</a> from <a>XMLHttpRequest</a> to begin playing a large video in <code>readystate</code> LOADING.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   268
			The example takes the <a>ReadableStream</a> from a <a href="#producers">producer</a>, <a>XMLHttpRequest</a>, and gives it to a <a href="#consumers">consumer</a>, the video tag.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   269
		</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   270
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   271
		<pre class="example">function handler() {
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   272
  if(this.readyState == this.LOADING) {
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   273
    var theStream = this.response;
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   274
    var streamURL = URL.createObjectURL(theStream);
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   275
    document.getElementById("myVideoTag").src = streamURL;
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   276
  }
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   277
}
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   278
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   279
var client = new XMLHttpRequest();
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   280
client.onreadystatechange = handler;
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   281
client.setRequestHeader('customHeader', 'value');
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   282
client.setRequestHeader('customHeader2', 'value2');
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   283
client.open("GET", "myvideo.h264");
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   284
client.responseType = "stream";
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   285
client.send();</pre>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   286
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   287
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   288
			In addition to the <a>ReadableStream</a> interface, this specification introduces an interface called <a>WritableStream</a> for data consuming APIs.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   289
			The <a>WritableStream</a> interface provides a <code>write()</code> method which allows applications to write data to a <a href="#consumers">data consuming API</a>.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   290
			<code>write()</code> supports writing bytes represented as a <a>Blob</a>, <a>ArrayBuffer</a>, or <a>DOMString</a>.
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   291
		</p>
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   292
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   293
			The example below demonstrates how to use <code>write()</code> to load a <a>ReadableStream</a> into the audio tag, whose data could be processed and built dynamically at read time.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   294
			ByteStream in the example is a class which implements both <a>WritableStream</a> and <a>ReadableStream</a>.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   295
			It accepts bytes generated by the code via <a>WritableStream</a> methods, and the written data will be consumed by the audio element via the object URL which is a part of <a>ReadableStream</a>'s functionality.
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   296
		</p>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   297
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   298
		<pre class="example">var stream = new ByteStream("audio/mp3");
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   299
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   300
function writeData() {
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   301
  // Do work to create more data to place into the stream
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   302
  var data = generateMusic();
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   303
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   304
  // If we have no more data to process and place in the stream, we close
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   305
  if (moreData == null){
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   306
    stream.writeClose();
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   307
  } else{
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   308
    // Wait until write() completes.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   309
    stream.write(data).then(
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   310
      function () {
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   311
        writeData();
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   312
      },
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   313
      function (error) {
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   314
        // Handle error
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   315
      }
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   316
    );
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   317
  }
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   318
}
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   319
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   320
var streamURL = URL.createObjectURL(stream);
8
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
   321
document.getElementById('audioTag').src = streamURL;
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
   322
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   323
writeData();</pre>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   324
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   325
		<p>
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   326
			A producer can also do work only when pulled by using <code>awaitSpaceAvailable()</code>, which will inform the producer when to produce data.
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   327
			This is useful when high-performance is necessary.
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   328
		</p>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   329
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   330
		<pre class="example">function poll() {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   331
  stream.awaitSpaceAvailable().then(
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   332
    function (pulledAmount) {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   333
      stream.write(generateRandomBytes(pulledAmount));
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   334
      poll();
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   335
    }
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   336
  );
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   337
}
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   338
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   339
poll();</pre>
113
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   340
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   341
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   342
			When X bytes are loaded and passed to the Promise, the ReadableStream marks X bytes used in pullAmount.
113
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   343
			The next <code>read()</code> call automatically clears the mask to request the producer to produce X more bytes.
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   344
			If precise flow control is needed, you update pullAmount before the next <code>read()</code>.
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   345
			In the example below, the producer is requested to produce 16 bytes, and then in the fulfill callback, pullAmount is set to the remaining number of bytes not to request more.
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   346
		</p>
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   347
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   348
		<pre class="example">stream.pullAmount = 16;
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   349
function read() {
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   350
  stream.read().then(
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   351
    function (result) {
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   352
      process(result);
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   353
      stream.pullAmount -= result.size;
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   354
      if (stream.pullAmount == 0) {
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   355
        // Done
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   356
      } else if (stream.eof) {
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   357
        // Done
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   358
      } else {
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   359
        read();
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   360
      }
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   361
    }
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   362
  );
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   363
}</pre>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   364
	</section>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   365
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   366
	<section class="section" id="writableByteStream">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   367
		<h2>WritableStream Interface</h2>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   368
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   369
			The WritableStream interface defines a protocol for APIs which consume byte streams.
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   370
			The protocol includes:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   371
			<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   372
				<li>How to receive the byte stream</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   373
				<li>How to notify the writer of completion of writing</li>
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   374
				<li>How to notify the writer of how much data can be accepted currently</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   375
			</ol>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   376
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   377
			By returning a <a>Promise</a> and delaying fulfillment of it, the WritableStream realizes flow control.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   378
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   379
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   380
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   381
			The actual data consumer behind the WritableStream is called a data sink and is identified by <dfn>dataSink</dfn>.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   382
			A data sink consumes byte streams and notifies the WritableStream of the number of bytes the data sink can newly accept.
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   383
			For each data sink, it's defined how to calculate <a>cost</a> of each object which the data sink can consume.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   384
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   385
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   386
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   387
			A WritableStream has a one-to-one mapping with the associated data sink, and has defined semantics for <a href='#interactingWithDataSink'>interacting with the data sink internally</a>.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   388
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   389
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   390
		<section class="section">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   391
			<h3>WritableStream interface</h3>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   392
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   393
			<dl class="idl" title="interface WritableStream">
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   394
				<dt>attribute DOMString writeEncoding</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   395
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   396
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   397
						Specifies a <a>DOMString</a> that represents the label of an encoding [[!EncodingDetermination]].
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   398
						If set, it will be used as part of the encoding determination used when processing a <a>DOMString</a> provided in a <code>write()</code> method call.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   399
						It will return the label last set, or the empty DOMString if never set.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   400
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   401
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   402
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   403
						This parameter is not designed to be specified as an argument of write() since it's not likely to be changed frequently.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   404
					</section>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   405
				</dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   406
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   407
				<dt>Promise&amp;lt;unsigned long long&gt; write()</dt>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   408
				<dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   409
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   410
						This method writes the specified <var>data</var> to the WritableStream.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   411
					</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   412
85
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   413
					<section class="note">
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   414
						<p>
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   415
							write() returns a Promise to make it easy for byte stream producing code to react to backpressure.
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   416
						</p>
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   417
					</section>
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   418
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   419
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   420
						This method must run the steps below:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   421
						<ol>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   422
							<li>Let <var>latchedEncoding</var> be the current value of <a href="#widl-WritableStream-writeEncoding">writeEncoding</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   423
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   424
							<li><a>Abort wait</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   425
115
14b1075d41d8 Define cost
Takeshi Yoshino <tyoshino@google.com>
parents: 111
diff changeset
   426
							<li>If <var>cost</var> argument is specified, let <var>amountToWrite</var> be <var>cost</var> argument. Otherwise, let <var>amountToWrite</var> be the <a>cost</a> of <var>data</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   427
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   428
							<li>Let <var>writePromise</var> be a new <a>Promise</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   429
98
3b89f8cea0fd More tuple -> pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents: 97
diff changeset
   430
							<li>Let <var>pendingWrite</var> be a new <a>PendingWriteDescriptor</a></li>
3b89f8cea0fd More tuple -> pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents: 97
diff changeset
   431
							<li>Set <var>pendingWrite.promise</var> to <var>writePromise</var></li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   432
							<li>Set <var>pendingWrite.amount</var> to <var>amountToWrite</var></li>
98
3b89f8cea0fd More tuple -> pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents: 97
diff changeset
   433
							<li>Push <var>pendingWrite</var> to <a>pendingWriteQueue</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   434
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   435
							<li><a>Process pendingWriteQueue</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   436
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   437
							<li>Return <var>writePromise</var>, and then continue to process the steps in this algorithm</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   438
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   439
							<li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   440
								<dl class="switch">
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   441
									<dt>If <var>data</var> is a <a>DOMString</a></dt>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   442
									<dd>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   443
										Write <var>data</var> to <a>dataSink</a> together with <var>latchedEncoding</var> as <var>encoding</var> parameter.
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   444
										Interpretation of <var>latchedEncoding</var> is up to <a>dataSink</a>.
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   445
									</dd>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   446
									<dt>Otherwise</dt>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   447
									<dd>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   448
										Write <var>data</var> to <a>dataSink</a>.
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   449
									</dd>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   450
								</dl>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   451
							</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   452
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   453
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   454
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   455
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   456
						If <var>data</var> argument is an <a>ArrayBufferView</a>, modifications made on the ArrayBufferView's contents between <code>write()</code> method call and fulfill of the returned Promise may affect the data written to <a>dataSink</a>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   457
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   458
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   459
					<dl class="parameters">
111
f3c425cc88db write accepts any data
Takeshi Yoshino <tyoshino@google.com>
parents: 110
diff changeset
   460
						<dt>any data</dt>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   461
						<dd>Data to write.</dd>
115
14b1075d41d8 Define cost
Takeshi Yoshino <tyoshino@google.com>
parents: 111
diff changeset
   462
						<dt>optional [Clamp] unsigned long long cost</dt>
14b1075d41d8 Define cost
Takeshi Yoshino <tyoshino@google.com>
parents: 111
diff changeset
   463
						<dd>Overrides <a>cost</a> of data.</dd>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   464
					</dl>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   465
				</dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   466
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   467
				<dt>Promise&amp;lt;unsigned long long&gt; awaitSpaceAvailable()</dt>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   468
				<dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   469
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   470
						This method waits until the WritableStream becomes able to accept any non-zero amount of data.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   471
						The returned <a>Promise</a> will be fulfilled with the number of bytes the WritableStream can accept.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   472
					</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   473
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   474
					<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   475
						This method must run the steps below:
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   476
						<ol>
110
6a7a40bde1e5 Abort wait -> abort waiting
Takeshi Yoshino <tyoshino@google.com>
parents: 109
diff changeset
   477
							<li><a>Abort waiting</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   478
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   479
							<li>Set <a>waitPromise</a> to a new <a>Promise</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   480
							<li>Return <a>waitPromise</a>, and then continue to process the steps in this algorithm</li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   481
							<li>Wait until <a>pendingWriteQueue</a> is empty and <a>spaceAvailable</a> is not 0</li>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   482
							<li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   483
								Queue a task to run the steps below:
38
3cdd8b2d21d9 Merging changes made for preparing WD
Takeshi Yoshino <tyoshino@google.com>
parents: 37
diff changeset
   484
								<ol>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   485
									<li>If <a>waitPromise</a> is <code>null</code>, terminate these steps</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   486
									<li>Let <var>detachedWaitPromise</var> be <a>waitPromise</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   487
									<li>Set <a>waitPromise</a> to <code>null</code></li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   488
									<li>Fulfill <var>detachedWaitPromise</var> with <a>spaceAvailable</a></li>
38
3cdd8b2d21d9 Merging changes made for preparing WD
Takeshi Yoshino <tyoshino@google.com>
parents: 37
diff changeset
   489
								</ol>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   490
							</li>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   491
						</ol>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   492
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   493
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   494
103
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   495
				<dt>Promise&amp;lt;undefined&gt; writeClose()</dt>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   496
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   497
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   498
						This method tells the WritableStream that no more data will be written to it.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   499
						Once writeClose() has been called on a WritableStream, no further method calls can be made on the WritableStream.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   500
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   501
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   502
					<p>
103
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   503
						This method must run the steps below:
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   504
						<ol>
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   505
							<li>Let <var>closePromise</var> be a new <a>Promise</a></li>
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   506
							<li>Return <var>closePromise</var>, and then continue the process the steps in this algorithm</li>
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   507
							<li>Write the EOF to <a>dataSink</a></li>
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   508
							<li>Wait until <a>dataSink</a> acknowledges the EOF</li>
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   509
							<li>Fulfill <var>closePromise</var> with <code>undefined</code></li>
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   510
						</ol>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   511
					</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   512
				</dd>
116
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   513
118
360cd31579a7 Make reason optional
Takeshi Yoshino <tyoshino@google.com>
parents: 117
diff changeset
   514
				<dt>Promise&amp;lt;undefined&gt; writeAbort(optional any reason)</dt>
116
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   515
				<dd>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   516
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   517
						This method tells the WritableStream that no more data will be written to it with indication of error.
116
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   518
						The details of the error will be given by <var>reason</var> argument.
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   519
						The interpretation of <var>reason</var> is up to <a>dataSink</a>.
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   520
						Once writeAbort() has been called on a WritableStream, no further method calls can be made on the WritableStream.
116
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   521
					</p>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   522
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   523
					<p>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   524
						This method must run the steps below:
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   525
						<ol>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   526
							<li>Let <var>abortPromise</var> be a new <a>Promise</a></li>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   527
							<li>Return <var>abortPromise</var>, and then continue the process the steps in this algorithm</li>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   528
							<li><a>Write-abort</a> <a>dataSink</a> with <var>reason</var></li>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   529
							<li>Wait until <a>dataSink</a> acknowledges the write-abort</li>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   530
							<li>Fulfill <var>abortPromise</var> with <code>undefined</code></li>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   531
						</ol>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   532
					</p>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   533
				</dd>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   534
			</dl>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   535
		</section>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   536
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   537
		<section class="section">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   538
			<h2>Data sink model</h2>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   539
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   540
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   541
				The data sink is the underlying mechanism which a <a>WritableStream</a> interacts with and stores its data in.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   542
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   543
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   544
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   545
				A data sink to which the <a>WritableStream</a> interface writes bytes can be anything which:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   546
				<ol>
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   547
					<li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   548
						Accepts data possibly together with a <a>DOMString</a> parameter named <var>encoding</var> indicating in what encoding the data must be interpreted.
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   549
					</li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   550
					<li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   551
						Accepts the EOF signal
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   552
					</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   553
					<li>
116
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   554
						Accepts the write-abort signal with an object parameter named reason.
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   555
					</li>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   556
					<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   557
						Notifies <a>WritableStream</a> of how much data the data sink can newly accept.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   558
						When and how to generate such notifications is up to data sinks.
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   559
						Data sinks must be able to accept data more than it notified <a>WritableStream</a> of.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   560
					</li>
103
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   561
					<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   562
						Notifies <a>WritableStream</a> of that the data sink is gone.
119
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   563
						This signal may mean an error.
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   564
						If it means an error, an object indicating the details of the error is attached.
116
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   565
					</li>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   566
					<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   567
						Notifies <a>WritableStream</a> of acknowledgement of the write-abort signal with error detail object.
103
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   568
					</li>
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   569
					<li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   570
						How to calculate an integer value <dfn>cost</dfn> of each object which the data sink can consume.
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   571
					</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   572
				</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   573
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   574
		</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   575
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   576
		<section class="section" id='interactingWithDataSink'>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   577
			<h2>Interacting with the data sink</h2>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   578
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   579
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   580
				This section defines the internal mechanisms for how the WritableStream interacts with <a>dataSink</a>.
93
33fa9ecdbe74 A bit tweak on data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 92
diff changeset
   581
				This section specifies both the internal properties as well as the algorithms.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   582
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   583
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   584
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   585
				A WritableStream has an associated integer variable <dfn>spaceAvailable</dfn> which holds the number of bytes that <a>dataSink</a> requested but not yet written to it.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   586
				This variable is initialized to 0 on construction.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   587
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   588
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   589
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   590
				A WritableStream has an associated <a>Promise</a> <dfn>waitPromise</dfn> which is used by the <code>awaitSpaceAvailable()</code> method.
93
33fa9ecdbe74 A bit tweak on data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 92
diff changeset
   591
				This variable is initialized to <code>null</code> on construction.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   592
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   593
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   594
			<p>
110
6a7a40bde1e5 Abort wait -> abort waiting
Takeshi Yoshino <tyoshino@google.com>
parents: 109
diff changeset
   595
				To <dfn>abort waiting</dfn>, run the steps below:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   596
				<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   597
					<li>If <a>waitPromise</a> is <code>null</code>, terminate these steps</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   598
					<li>Let <var>detachedWaitPromise</var> be <a>waitPromise</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   599
					<li>Set <a>waitPromise</a> to <code>null</code></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   600
					<li>Reject <var>detachedWaitPromise</var> with an "<code><a>AbortError</a></code>"</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   601
				</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   602
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   603
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   604
			<p>
94
e06bf08768db Formatting data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 93
diff changeset
   605
				A struct type <dfn>PendingWriteDescriptor</dfn> has the following members:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   606
				<ul>
91
3ed9f08a1f23 Renames for readability
Takeshi Yoshino <tyoshino@google.com>
parents: 90
diff changeset
   607
					<li>A <a>Promise</a> <var>promise</var></li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   608
					<li>An integer <var>amount</var></li>
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   609
					<li>An integer <var>ackedAmount</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   610
				</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   611
			</p>
94
e06bf08768db Formatting data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 93
diff changeset
   612
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   613
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   614
				A WritableStream has an associated queue <dfn>pendingWriteQueue</dfn> which holds <a>PendingWriteDescriptor</a>s.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   615
				This queue is initialized to an empty queue on construction.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   616
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   617
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   618
			<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   619
				To <dfn>process pendingWriteQueue</dfn>, repeat the steps below:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   620
				<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   621
					<li>If <a>pendingWriteQueue</a> is empty, break from this loop</li>
91
3ed9f08a1f23 Renames for readability
Takeshi Yoshino <tyoshino@google.com>
parents: 90
diff changeset
   622
					<li>Let <var>pendingWrite</var> be the head element of <a>pendingWriteQueue</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   623
					<li>
119
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   624
						<dl class="switch">
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   625
							<dt>If <a>sinkGone</a> is set</dt>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   626
							<dd>Run the steps below:
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   627
								<ol>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   628
									<li>Pop <var>pendingWrite</var> from <a>pendingWriteQueue</a>, and then</li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   629
									<li>If <var>pendingWrite.promise</var> is not <code>null</code>, reject it with <a>sinkErrorDetail</a></li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   630
								</ol>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   631
							</dd>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   632
							<dt>Otherwise</dt>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   633
							<dd>Run the steps below:
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   634
								<ol>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   635
									<li>Let <var>amountToAcknowledge</var> be min(<var>pendingWrite.amount</var> - <var>pendingWrite.ackedAmount</var>, <a>spaceAvailable</a>)</li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   636
									<li>Set <a>spaceAvailable</a> to <a>spaceAvailable</a> - <var>amountToAcknowledge</var></li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   637
									<li>Set <var>pendingWrite.ackedAmount</var> to <var>pendingWrite.ackedAmount</var> + <var>amountToAcknowledge</var></li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   638
									<li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   639
										If <var>pendingWrite.ackedAmount</var> equals to <var>pendingWrite.amount</var>, run the steps below:
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   640
										<ol>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   641
											<li>Pop <var>pendingWrite</var> from <a>pendingWriteQueue</a></li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   642
											<li>If <var>pendingWrite.promise</var> is not <code>null</code>, fulfill it with <var>pendingWrite.amount</var></li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   643
										</ol>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   644
									</li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   645
								</ol>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   646
							</dd>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   647
						</dl>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   648
					</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   649
				</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   650
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   651
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   652
			<p>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   653
				When <a>dataSink</a> requests <var>amountNewlyRequested</var> more data, queue a task which runs the steps below:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   654
				<ol>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   655
					<li>Set <a>spaceAvailable</a> to <a>spaceAvailable</a> + <var>amountNewlyRequested</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   656
					<li><a>Process pendingWriteQueue</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   657
				</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   658
			</p>
119
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   659
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   660
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   661
				A WritableStream has an associated flag <dfn>sinkGone</dfn> which is set when the data sink is gone.
119
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   662
			</p>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   663
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   664
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   665
				A WritableStream has an associated object <dfn>sinkErrorDetail</dfn> which is initialized to null, and when the data sink is gone, set to the error detail object.
119
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   666
			</p>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   667
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   668
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   669
				When <a>dataSink</a> notifies the WritableStream of that the data sink is gone, queue a task which runs the steps below:
119
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   670
				<ol>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   671
					<li>Set <a>sinkGone</a></li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   672
					<li>Set <a>sinkErrorDetail</a> to the error detail object</li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   673
					<li><a>Process pendingWriteQueue</a></li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   674
				</ol>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   675
			</p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   676
		</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   677
	</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   678
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   679
	<section class="section" id="readableByteStream">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   680
		<h2>ReadableStream Interface</h2>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   681
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   682
			The ReadableStream interface defines a protocol for APIs which produce a byte stream. This protocol includes:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   683
			<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   684
				<li>How to receive a read request from the reader and output bytes</li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   685
				<li>How to transfer data in bulk to another <a>WritableStream</a> (by using the <code>pipe()</code> method)</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   686
				<li>How to mirror data to multiple destinations (by using the <code>fork()</code>)</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   687
			</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   688
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   689
			By returning a <a>Promise</a> and delaying fulfillment of it, the ReadableStream realizes asynchronous data consumption.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   690
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   691
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   692
		<p>
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   693
			Interfaces introduced in this section provide simple and convenient ways to consume data.
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   694
			They connect arbitrary byte stream producer and byte stream consuming JavaScript code using Promises and method invocations.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   695
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   696
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   697
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   698
			A ReadableStream has a one-to-one mapping with an associated data source, and has defined semantics for <a href='#interactingWithDataSource'>interacting with the data source internally</a>.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   699
			A data source, however, can have a one-to-many relationship with ReadableStream, in cases where <code>fork()</code> is used.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   700
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   701
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   702
		<section class="section" id="readableByteStreamInterface">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   703
			<h3>ReadableStream interface</h3>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   704
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   705
			<dl class="idl" title="interface ReadableStream">
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   706
				<dt>readonly attribute DOMString type</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   707
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   708
					Returns the ASCII-encoded string in lower case representing the media type of the <code>Stream</code>,
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   709
					expressed as an RFC2046 MIME type [[!RFC2046]].
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   710
					Conforming user agents SHOULD return the MIME type of the <code>ReadableStream</code>, if it is known.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   711
					If conforming user agents cannot determine the media type of the <code>ReadableStream</code>, they MUST return the empty string.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   712
					A string is a valid MIME type if it matches the media-type token defined in section 3.7 "Media Types" of RFC 2616 [[!HTTP11]].
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   713
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   714
125
98448480356b ByteStreamReadType -> StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents: 124
diff changeset
   715
				<dt>attribute StreamReadType readBinaryAs</dt>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   716
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   717
					<p>
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   718
						Specifies what data type will be returned by a <code>read()</code> and <code>readUpTo()</code> method call.
125
98448480356b ByteStreamReadType -> StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents: 124
diff changeset
   719
						This attribute can be set to any of the supported types in <a>StreamReadType</a>.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   720
						The default value for this attribute is "<code>arraybuffer</code>".
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   721
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   722
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   723
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   724
				<dt>attribute DOMString readEncoding</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   725
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   726
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   727
						Specifies a <a>DOMString</a> that represents the label of an encoding [[!EncodingDetermination]].
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   728
						If set, it will be used as part of the encoding determination used when processing a <code>read()</code> method call.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   729
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   730
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   731
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   732
						This parameter is not designed to be specified as an argument of <code>read()</code> since it's not likely to be changed frequently.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   733
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   734
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   735
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   736
				<dt>attribute unsigned long long pullAmount</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   737
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   738
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   739
						This attribute provides ReadableStream with a hint of how much data the reader can consume currently.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   740
						Each implementation of ReadableStream must initialize the value of pullAmount on construction.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   741
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   742
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   743
					<p>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   744
						When this attribute is set, <a>retrieve data</a>.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   745
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   746
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   747
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   748
						This flow control functionality is provided as a separated attribute rather than as an argument of the read() method based on the assumption that this value is not changed frequently.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   749
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   750
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   751
						It's possible that the number of bytes received by <code>read()</code> is more than the pullAmount value.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   752
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   753
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   754
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   755
				<dt>Promise&amp;lt;StreamReadResult&gt; readUpTo()</dt>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   756
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   757
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   758
						This method reads data from the ReadableStream.
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   759
						The returned <a>Promise</a> is fulfilled only when the total cost of produced data becomes equal to or greater than the specified <a>cost</a> or the EOF is reached.
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   760
						The cost of data returned by this method is the same or less than the specified <var>size</var> argument.
121
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   761
						The cost of data returned by this method can be less than <var>size</var> when data cannot be fully converted into the type specified by <code>readBinaryAs</code> or an EOF was reached.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   762
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   763
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   764
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   765
						This method must run the steps below:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   766
						<ol>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   767
							<li>If <a href="#widl-ReadableStream-readBinaryAs">readBinaryAs</a> is "<code>text</code>" throw a "<code><a>SyntaxError</a></code>"</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   768
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   769
							<li>If <a>readPending</a> is set, throw an "<code><a>InvalidStateError</a></code>"</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   770
							<li>Set <a>readPending</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   771
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   772
							<li>Let <var>latchedType</var> be the current value of <a href="#widl-ReadableStream-readBinaryAs">readBinaryAs</a></li>
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   773
							<li>Let <var>latchedEncoding</var> be the current value of <a href="#widl-ReadableStream-readEncoding">readEncoding</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   774
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   775
							<li>Set <a>readUpToPullAmount</a> to <var>size</var></li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   776
							<li>Set <a>amountBeingReturned</a> to 0</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   777
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   778
							<li><a>Retrieve data</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   779
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   780
							<li>Let <var>readPromise</var> be a new <a>Promise</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   781
							<li>Return <var>readPromise</var>, and then continue to process the steps in this algorithm</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   782
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   783
							<li>Wait until the total cost of data in <a>readDataBuffer</a> becomes equal to or greater than <var>size</var> or <a>eofReached</a> is set</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   784
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   785
							<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   786
								Queue a task which runs the steps below:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   787
								<ol>
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   788
									<li>Let <var>readableAmount</var> be the total cost of data in <a>readDataBuffer</a></li>
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   789
									<li>Let <var>maxAmountToConsume</var> be min(<var>size</var>, <var>readableAmount</var>)</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   790
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   791
									<li>Let <var>result</var> be a new <a>StreamReadResult</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   792
									<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   793
										<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   794
											<dt>If <var>latchedType</var> is "<code>none</code>"</dt>
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   795
											<dd>
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   796
												<ol>
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   797
													<li>Set <var>result</var>.<a href="#widl-StreamReadResult-data">data</a> to <code>undefined</code></li>
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   798
													<li>Pop data from <a>readDataBuffer</a> as much as possible but up to <var>maxAmountToConsume</var></li>
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   799
												</ol>
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   800
											</dd>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   801
											<dt>Otherwise</dt>
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   802
											<dd>
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   803
												<ol>
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   804
													<li>Set <var>result</var>.<a href="#widl-StreamReadResult-data">data</a> to an object of the type specified by <var>latchedType</var> that can be created by consuming as much data as possible from <a>readDataBuffer</a> but up to <var>maxAmountToConsume</var></li>
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   805
													<li>Pop the consumed data from <a>readDataBuffer</a></li>
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   806
											</dd>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   807
										</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   808
									</li>
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   809
									<li>Let <var>amountConsumed</var> be the total cost of data consumed in the last step</li>
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   810
									<li>Set <a href="#widl-StreamReadResult-amountConsumed">amountConsumed</a> of <var>result</var> to <var>amountConsumed</var></li>
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   811
									<li>Set <a href="#widl-StreamReadResult-eof">eof</a> of <var>result</var> to <code>true</code> if <a>readDataBuffer</a> is empty and <a>eofReached</a> is set</li>
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   812
									<li>Set <var>result</var>.<a href="#widl-StreamReadResult-error">error</a> to <a>sourceErrorDetail</a></li>
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   813
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   814
									<li>Set <a>amountBeingReturned</a> to <var>amountConsumed</var></li>
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   815
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   816
									<li>Set <a>readUpToPullAmount</a> to 0</li>
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   817
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   818
									<li>Unset <a>readPending</a></li>
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   819
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   820
									<li>Fulfill <var>readPromise</var> with <var>result</var></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   821
								</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   822
							</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   823
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   824
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   825
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   826
					<dl class="parameters">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   827
						<dt>[Clamp] unsigned long long size</dt>
114
6cd4d6696cb8 Change readExact to readUpTo and make it able to handle non-byte type data
Takeshi Yoshino <tyoshino@google.com>
parents: 113
diff changeset
   828
						<dd>Max number of bytes to read.</dd>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   829
					</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   830
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   831
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   832
						This method is useful if
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   833
						<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   834
							<li>You don't want to get notified of new data unless bytes of the specified number become available.</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   835
							<li>You don't want to get your data fragmented into multiple parts, thus avoiding the need to buffer and combine chunks yourself.</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   836
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   837
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   838
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   839
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   840
				<dt>Promise&amp;lt;StreamReadResult&gt; read()</dt>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   841
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   842
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   843
						This method reads data from the ReadableStream.
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   844
						The speed of reading can be roughly adjusted by using <a href="#widl-StreamReadResult-pullAmount">pullAmount</a>.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   845
						pullAmount doesn't necessarily limit the size of data being read by this method.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   846
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   847
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   848
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   849
						This method must run the steps below:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   850
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   851
						<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   852
							<li>If <a>readPending</a> is set, throw an "<code><a>InvalidStateError</a></code>"</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   853
							<li>Set <a>readPending</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   854
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   855
							<li>Let <var>latchedType</var> be the current value of <a href="#widl-ReadableStream-readBinaryAs">readBinaryAs</a> attribute</li>
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   856
							<li>Let <var>latchedEncoding</var> be the current value of <a href="#widl-ReadableStream-readEncoding">readEncoding</a> attribute</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   857
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   858
							<li>Set <a>amountBeingReturned</a> to 0</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   859
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   860
							<li><a>Retrieve data</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   861
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   862
							<li>Let <var>readPromise</var> be a new <a>Promise</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   863
							<li>Return <var>readPromise</var>, and then continue to process the steps in this algorithm</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   864
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   865
							<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   866
								<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   867
									<dt>If <var>latchedType</var> is "<code>text</code>"</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   868
									<dd>
121
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   869
										Wait until any of the following conditions is met, and then run the steps for the condition:
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   870
										<dl class="switch">
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   871
											<dt>All or part of bytes in <a>readDataBuffer</a> can be converted into a non-empty <a>DOMString</a> when decoded using <var>latchedEncoding</var></dt>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   872
											<dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   873
												<ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   874
													<li>Pop the bytes from <a>readDataBuffer</a></li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   875
													<li>Let <var>amountConsumed</var> be the number of the popped bytes</li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   876
													<li>Let <var>readData</var> be the result of decoding</li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   877
												</ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   878
											</dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   879
											<dt>It's clear decoding bytes in <a>readDataBuffer</a> using <var>latchedEncoding</var> fails regardless bytes to be retrieved in the future are</dt>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   880
											<dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   881
												<ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   882
													<li>Reject <var>readPromise</var> with an "<code><a>InvalidStateError</a></code>"</li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   883
													<li>Terminate these steps</li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   884
												</ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   885
											</dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   886
											<dt>Anything that doesn't represent bytes in <a>readDataBuffer</a> is encountered</dt>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   887
											<dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   888
												<ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   889
													<li>Reject <var>readPromise</var> with an "<code><a>InvalidStateError</a></code>"</li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   890
													<li>Terminate these steps</li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   891
												</ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   892
											</dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   893
										</dl>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   894
									</dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   895
									<dt>If <var>latchedType</var> is "<code>arraybuffer</code>" or "<code>blob</code>"</dt>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   896
									<dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   897
										Wait until any of the following conditions is met, and then run the steps for the condition:
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   898
										<dl class="switch">
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   899
											<dt>There're non-zero number of bytes in <a>readDataBuffer</a></dt>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   900
											<dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   901
												<ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   902
													<li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   903
														Pop the bytes from <a>readDataBuffer</a>, and then let <var>readBytes</var> be the popped bytes
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   904
														<section class="note">
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   905
															Implementations may choose to pop only part of bytes readable if it helps reducing memory copy.
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   906
														</section>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   907
													</li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   908
													<li>Let <var>readData</var> be an object of the type specified by <var>latchedType</var> which represents <var>readBytes</var></li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   909
													<li>Let <var>amountConsumed</var> be the number of the popped bytes</li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   910
												</ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   911
											</dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   912
											<dt>Anything that doesn't represent bytes in <a>readDataBuffer</a> is encountered</dt>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   913
											<dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   914
												<ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   915
													<li>Reject <var>readPromise</var> with an "<code><a>InvalidStateError</a></code>"</li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   916
													<li>Terminate these steps</li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   917
												</ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   918
											</dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   919
										</dl>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   920
									</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   921
									<dt>Otherwise</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   922
									<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   923
										<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   924
											<li>Wait until <a>readDataBuffer</a> becomes non-empty or <a>eofReached</a> is set</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   925
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   926
												<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   927
													<dt>If <var>latchedType</var> is "<code>none</code>"</dt>
121
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   928
													<dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   929
														<ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   930
															<li>Pop data from <a>readDataBuffer</a></li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   931
															<li>Let <var>readData</var> be <code>undefined</code></li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   932
														</ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   933
													</dd>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   934
													<dt>Otherwise</dt>
121
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   935
													<dd>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   936
														<ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   937
															<li>Pop data from <a>readDataBuffer</a></li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   938
															<li>Let <var>readData</var> be an object representing the data</li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   939
															<li>Let <var>amountConsumed</var> be the <a>cost</a> of the data</li>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   940
														</ol>
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   941
													</dd>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   942
												</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   943
											</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   944
										</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   945
									</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   946
								</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   947
							</li>
121
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   948
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   949
							<li>Queue a task which runs the rest of this algorithm</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   950
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   951
							<li>Let <var>result</var> be a new <a>StreamReadResult</a>.</li>
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   952
							<li>Set <var>result</var>.<a href="#widl-StreamReadResult-data">data</a> to <var>readData</var></li>
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   953
							<li>Set <var>result</var>.<a href="#widl-StreamReadResult-eof">eof</a> to <code>true</code> if <a>eofReached</a> is set and <a>readDataBuffer</a> is empty</li>
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   954
							<li>Set <var>result</var>.<a href="#widl-StreamReadResult-amountConsumed">amountConsumed</a> to <var>amountConsumed</var></li>
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   955
							<li>Set <var>result</var>.<a href="#widl-StreamReadResult-error">error</a> to <a>sourceErrorDetail</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   956
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   957
							<li>Set <a>amountBeingReturned</a> to <var>amountConsumed</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   958
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   959
							<li>Unset <a>readPending</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   960
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   961
							<li>Fulfill <var>readPromise</var> with <var>result</var></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   962
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   963
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   964
78
12c164bee09f Add diagrams
Takeshi Yoshino <tyoshino@google.com>
parents: 77
diff changeset
   965
					<p>
83
afed6501a898 moved images, fixed typos, fixed header
fmoussa <feras.moussa@hotmail.com>
parents: 81
diff changeset
   966
						<img src="images/fulfilling.png" alt="How new data is automatically fetched">
78
12c164bee09f Add diagrams
Takeshi Yoshino <tyoshino@google.com>
parents: 77
diff changeset
   967
					</p>
12c164bee09f Add diagrams
Takeshi Yoshino <tyoshino@google.com>
parents: 77
diff changeset
   968
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   969
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   970
						This method is useful if
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   971
						<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   972
							<li>You don't care in what size and as how many fragments the data will be received</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   973
							<li>You want to limit the number of bytes read for flow control</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   974
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   975
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   976
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   977
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   978
				<dt>Promise&amp;lt;StreamReadResult&gt; pipe()</dt>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   979
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   980
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   981
						This method bulk transfers bytes from the ReadableStream to another <a>WritableStream</a>.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   982
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   983
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   984
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   985
						Fulfillment of the returned Promise doesn't necessarily mean that the data transferred to <var>destination</var> has been successfully read from it.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   986
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   987
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   988
					<section class="note">
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   989
						TODO: Rewrite this to update <a>amountBeingReturned</a> as numBytesAcknowledged of <a>PendingWriteDescriptor</a>s are updated
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   990
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   991
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   992
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   993
						This method must run the steps below:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   994
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   995
						<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   996
							<li>If <a>readPending</a> is set, throw an "<code><a>InvalidStateError</a></code>"</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   997
							<li>Set <a>readPending</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   998
110
6a7a40bde1e5 Abort wait -> abort waiting
Takeshi Yoshino <tyoshino@google.com>
parents: 109
diff changeset
   999
							<li>Run <a>abort waiting</a> algorithm on <var>destination</var></a>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1000
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1001
							<li>Set <a>amountBeingReturned</a> to 0</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1002
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1003
							<li><a>Retrieve data</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1004
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1005
							<li>Let <var>pipePromise</var> be a new <a>Promise</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1006
							<li>Return <var>pipePromise</var>, and then continue to process the steps in this algorithm</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1007
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1008
							<li>Let <var>totalAmountTransferred</var> be 0</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1009
							<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1010
								Repeat the steps below:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1011
								<ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1012
									<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1013
										Whenever <a>readDataBuffer</a> is not empty or <a>eofReached</a> is set,
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1014
										<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1015
											<dt>If this happened in the event loop</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1016
											<dd>Run the steps below</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1017
											<dt>Otherwise</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1018
											<dd>Queue a task which runs the steps below</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1019
										</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1020
										<ol>
100
7421b9a22a7e More bug fix in pipe(). numBytesRequested is used where numBytesSpaceAvailable must be used.
Takeshi Yoshino <tyoshino@google.com>
parents: 99
diff changeset
  1021
											<li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1022
												Let <var>readableAmount</var> be the number of bytes in <a>readDataBuffer</a>
100
7421b9a22a7e More bug fix in pipe(). numBytesRequested is used where numBytesSpaceAvailable must be used.
Takeshi Yoshino <tyoshino@google.com>
parents: 99
diff changeset
  1023
												<section class="note">
7421b9a22a7e More bug fix in pipe(). numBytesRequested is used where numBytesSpaceAvailable must be used.
Takeshi Yoshino <tyoshino@google.com>
parents: 99
diff changeset
  1024
													It's fine to process only part of the bytes, and process the rest in the next task.
7421b9a22a7e More bug fix in pipe(). numBytesRequested is used where numBytesSpaceAvailable must be used.
Takeshi Yoshino <tyoshino@google.com>
parents: 99
diff changeset
  1025
												</section>
7421b9a22a7e More bug fix in pipe(). numBytesRequested is used where numBytesSpaceAvailable must be used.
Takeshi Yoshino <tyoshino@google.com>
parents: 99
diff changeset
  1026
											</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1027
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1028
												<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1029
													<dt>If <var>size</var> is specified</dt>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1030
													<dd>Let <var>amountToTransfer</var> be min(<var>size</var> - <var>totalAmountTransferred</var>, <var>readableAmount</var>)</dd>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1031
													<dt>Otherwise</dt>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1032
													<dd>Let <var>amountToTransfer</var> be <var>readableAmount</var></dd>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1033
												</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1034
											</li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1035
											<li>Set <a>amountBeingReturned</a> to <a>amountBeingReturned</a> + <var>amountToTransfer</var></li>
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1036
											<li>Pop <var>amountToTransfer</var> bytes from <a>readDataBuffer</a>, and then write it to <a>dataSink</a> of <var>destination</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1037
98
3b89f8cea0fd More tuple -> pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents: 97
diff changeset
  1038
											<li>Let <var>pendingWrite</var> be a new <a>PendingWriteDescriptor</a></li>
3b89f8cea0fd More tuple -> pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents: 97
diff changeset
  1039
											<li>Set <var>pendingWrite.promise</var> to <code>null</code></li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1040
											<li>Set <var>pendingWrite.amount</var> to <var>amountToTransfer</var></li>
98
3b89f8cea0fd More tuple -> pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents: 97
diff changeset
  1041
											<li>Push <var>pendingWrite</var> to <a>pendingWriteQueue</a> of <var>destination</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1042
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1043
											<li>Set <var>totalAmountTransferred</var> to <var>totalAmountTransferred</var> + <var>amountToTransfer</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1044
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1045
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1046
												<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1047
													<dt>If <a>eofReached</a> is set</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1048
													<dd>Break from this loop</dd>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1049
													<dt>If <var>size</var> is specified and <var>totalAmountTransferred</var> equals to <var>size</var></dt>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1050
													<dd>Break from this loop</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1051
												</dl>
102
a176607d4c3a TODO about pipe() finish timing
Takeshi Yoshino <tyoshino@google.com>
parents: 101
diff changeset
  1052
												<section class="note">
a176607d4c3a TODO about pipe() finish timing
Takeshi Yoshino <tyoshino@google.com>
parents: 101
diff changeset
  1053
													Need to revisit. Finish when write to the destination completes?
a176607d4c3a TODO about pipe() finish timing
Takeshi Yoshino <tyoshino@google.com>
parents: 101
diff changeset
  1054
												</section>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1055
											</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1056
										</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1057
									</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1058
									<li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1059
										Whenever <a>pendingWriteQueue</a> of <var>destination</var> is empty and <a>spaceAvailable</a> of <var>destination</var> is not 0,
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1060
										<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1061
											<dt>If this happened in the event loop</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1062
											<dd>Run the steps below</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1063
											<dt>Otherwise</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1064
											<dd>Queue a task which runs the steps below</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1065
										</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1066
										<ol>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1067
											<li>Let <var>destSpaceAvailable</var> be <a>spaceAvailable</a> of <var>destination</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1068
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1069
												<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1070
													<dt>If <var>size</var> is specified</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1071
													<dd>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1072
														Set <a>pipePullAmount</a> to min(<var>size</var> - <var>totalAmountTransferred</var>, <var>destSpaceAvailable</var>)
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1073
														<section class="note">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1074
															If <a href="#widl-ReadableStream-pullAmount">pullAmount</a> is set to 0, pipe() transfers data in pull style.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1075
															I.e. only bytes of the same number as the number of bytes writable to <var>destination</var> are retrieved from the data source.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1076
														</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1077
														<section class="note">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1078
															Setting <a href="#widl-ReadableStream-pullAmount">pullAmount</a> to a small value doesn't have an effect of throttling the pace of pipe().
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1079
														</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1080
													</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1081
													<dt>Otherwise</dt>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1082
													<dd>Set <a>pipePullAmount</a> to <var>destSpaceAvailable</var></dd>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1083
												</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1084
											</li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1085
											<li>Set <a>amountBeingReturned</a> to 0</li>
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1086
											<li><a>Retrieve data</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1087
										</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1088
									</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1089
								</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1090
							</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1091
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1092
							<li>Set <a>pipePullAmount</a> to 0</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1093
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1094
							<li>Unset <a>readPending</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1095
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
  1096
							<li>Let <var>result</var> be a new <a>StreamReadResult</a></li>
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
  1097
							<li>Set <var>result</var>.<a href="#widl-StreamReadResult-data">data</a> to <code>undefined</code>.
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
  1098
							<li>Set <var>result</var>.<a href="#widl-StreamReadResult-eof">eof</a> to <code>true</code> if <a>eofReached</a></li>
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
  1099
							<li>Set <var>result</var>.<a href="#widl-StreamReadResult-amountConsumed">amountConsumed</a> to <var>totalAmountTransferred</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1100
							<li>
101
7da4a886ff9f More pipe() bug fixes
Takeshi Yoshino <tyoshino@google.com>
parents: 100
diff changeset
  1101
								Fulfill <var>pipePromise</var> with <var>result</var>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1102
								<section class="note">
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1103
									At this point, <a>amountBeingReturned</a> is not yet reset
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1104
								</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1105
							</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1106
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1107
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1108
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1109
					<dl class="parameters">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1110
						<dt>WritableStream destination</dt>
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1111
						<dd>Destination <a>WritableStream</a>.</dd>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1112
						<dt>optional [Clamp] unsigned long long size</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1113
						<dd>Number of bytes to transfer.</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1114
					</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1115
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1116
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1117
				<dt>ReadableStream fork()</dt>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1118
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1119
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1120
						This method creates a new ReadableStream which refers to the same <a>dataSource</a> as the current ReadableStream.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1121
						Data sources are range reference counted so that a range in a data source is freed only when all the ReadableStreams sharing the data source finish consuming it.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1122
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1123
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1124
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1125
						This method must run the steps below:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1126
						<ol>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1127
							<li>Let <var>branch</var> be a new ReadableStream which refers to <a>dataSource</a> and has the same <a>amountRequested</a> value, <a>readDataBuffer</a> contents and <a>eofReached</a> value as the current ReadableStream.</li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1128
							<li>If <a>amountRequested</a> is not 0, up to <a>amountRequested</a> bytes arriving in the future must be forwarded to <var>branch</var>.</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1129
							<li>Return <var>branch</var>.</li>