Overview.htm
author Takeshi Yoshino <tyoshino@google.com>
Tue, 28 Jan 2014 13:01:17 +0900
changeset 133 ecde9f975249
parent 132 fc2bc870e7a8
child 134 fda5141dff5d
permissions -rw-r--r--
Split data output code from read() and readUpTo() algorithm
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>
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   149
				A list of notable data <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>
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   155
				Extensions to <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-createObjectURL">URL.createObjectURL</a> and <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
   156
			</li>
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   157
		</ul>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   158
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   159
		<p>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   160
			This API is designed to be used in conjunction with other APIs and elements on the web platform, notably:
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   161
			<ul>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   162
				<li><a href="http://dev.w3.org/2006/webapi/FileAPI">FileAPI</a> [[!FILE-API]]</li>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   163
				<li>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   164
					<a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2">XMLHttpRequest</a>.
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   165
					E.g. with an overloaded <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-send-method"><code>send()</code></a> method 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]].
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   166
				</li>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   167
				<li><a href="http://dev.w3.org/html5/postmsg/#dom-window-postmessage"><code>postMessage</code></a></li>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   168
				<li>Web Workers [[!WEBWORKERS]]</li>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   169
			</ul>
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   170
		</p>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   171
	</section>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   172
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   173
	<section id="introduction" class="section informative">
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   174
		<h2>Introduction</h2>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   175
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   176
		<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   177
			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.
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   178
			This specification defines the basic representation for streams of data, 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
   179
		</p>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   180
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   181
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   182
			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
   183
			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.
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   184
			The data is written to the internal data sink inside the 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
   185
			<ul>
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   186
				<li>
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   187
					The <code>write()</code> method which writes the given data to the data sink
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   188
				</li>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   189
				<li>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   190
					The <code>awaitSpaceAvailable()</code> method which allows a data producing code to write data to the data consuming API only when its data sink is available to consume more data.
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   191
					This is useful for cases where an app may want to avoid filling the internal buffer.
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   192
				</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   193
			</ul>
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   194
			Actual transfer of data to the data sink may happen either synchronously or asynchronously.
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   195
			<a>WritableStream</a> hides the details of actual communication with the data sink while allowing for an efficient transfer of data.
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   196
		</p>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   197
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   198
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   199
			The <a>ReadableStream</a> interface defines a general protocol for <a href="#producers">data producing APIs</a> to communicate with data consuming code.
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   200
			This interface represents the potential for an infinite amount of data which are obtained over time and read once.
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   201
			Data consuming code reads data from the internal data source inside the data producing API using:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   202
			<ul>
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   203
				<li>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   204
					The <code>read()</code> and <code>readUpTo()</code> methods which reads data from the data source
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   205
				</li>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   206
				<li>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   207
					The <code>pullAmount</code> attribute which paces data retrieval from the data source
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   208
				</li>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   209
				<li>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   210
					The <code>pipe()</code> method which transfers data in bulk from the data source into the data sink of another API which implements <a>WritableStream</a>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   211
				</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   212
			</ul>
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   213
			Actual transfer of data from the data source may happen either synchronously or asynchronously.
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   214
			The <a>ReadableStream</a> hides the details of actual communication with the data source while allowing for an efficient transfer of data.
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   215
		</p>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   216
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   217
		<p>
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   218
			With the combination of the following features, this interface suite responds to various simple and complex needs of data stream handling.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   219
			<ul>
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   220
				<li>Delayed notification of completion by using <a>Promise</a>s. See below for more details.</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   221
				<li>Explicit back pressure management by propagating room for consumption back to producers</li>
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   222
				<li><a>WritableStream</a> always accepts incoming data synchronously to bridge with legacy APIs that don't understand backpressure</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   223
			</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   224
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   225
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   226
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   227
			The <a>ByteStream</a> is a simple implementation of both the <a>WritableStream</a> and <a>ReadableStream</a> interface.
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   228
			A ByteStream has a single queue of bytes which 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
   229
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   230
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   231
		<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   232
			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
   233
			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
   234
			Error conditions that may arise during an operation will be handled by the reject callback set to the Promise.
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   235
		</p>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   236
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   237
		<p>
131
5db012bd990c Make URI stuff more separate
Takeshi Yoshino <tyoshino@google.com>
parents: 130
diff changeset
   238
			The base stream classes are defined as JavaScript primitives.
5db012bd990c Make URI stuff more separate
Takeshi Yoshino <tyoshino@google.com>
parents: 130
diff changeset
   239
			Extensions to it for use in browsers are defined separately.
5db012bd990c Make URI stuff more separate
Takeshi Yoshino <tyoshino@google.com>
parents: 130
diff changeset
   240
		</p>
5db012bd990c Make URI stuff more separate
Takeshi Yoshino <tyoshino@google.com>
parents: 130
diff changeset
   241
5db012bd990c Make URI stuff more separate
Takeshi Yoshino <tyoshino@google.com>
parents: 130
diff changeset
   242
		<p>
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   243
			Examples below will be illustrative.
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   244
		</p>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   245
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   246
		<p>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   247
			The example below demonstrates how to read a chunk of data from a <a>ReadableStream</a> using <code>read()</code>.
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   248
			The <a>ReadableStream</a> may of come from a <a href="#producers">producer</a> such as <code>XMLHttpRequest</code>.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   249
		</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   250
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   251
		<pre class="example">
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   252
// Tell stream that we're ready to consume 1024 bytes.
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   253
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
   254
stream.readEncoding = "UTF-8";
121
cbc891d653dd Remove stale text
Takeshi Yoshino <tyoshino@google.com>
parents: 120
diff changeset
   255
stream.readBinaryAs = "arraybuffer";
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   256
stream.read().then(
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   257
  function (result) {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   258
    // Process data
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   259
  },
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   260
  function (error) {
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   261
    // Handle error
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   262
  });</pre>
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   263
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   264
		<p>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   265
			The example below demonstrates how to read bytes from a <a>ReadableStream</a> until an EOF is encountered.
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   266
		</p>
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   267
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   268
		<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
   269
function readUntilEof() {
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   270
  stream.read().then(
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   271
    function (result) {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   272
      processData(result.data);
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   273
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   274
      if (!result.eof) {
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   275
        readUntilEof();
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   276
      }
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   277
    },
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   278
    function (error) {
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   279
      // Handle error
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   280
    });
8
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
   281
}
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   282
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   283
readUntilEof();</pre>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   284
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   285
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   286
			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
   287
			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.
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   288
			If the consumer implements the <a>WritableStream</a> interface, we could use <code>pipe()</code> to transfer data to it instead of URL.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   289
		</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   290
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   291
		<pre class="example">function handler() {
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   292
  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
   293
    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
   294
    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
   295
    document.getElementById("myVideoTag").src = streamURL;
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   296
  }
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   297
}
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   298
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   299
var client = new XMLHttpRequest();
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   300
client.onreadystatechange = handler;
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   301
client.setRequestHeader('customHeader', 'value');
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   302
client.setRequestHeader('customHeader2', 'value2');
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   303
client.open("GET", "myvideo.h264");
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   304
client.responseType = "stream";
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   305
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
   306
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   307
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   308
			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
   309
			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
   310
			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
   311
		</p>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   312
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   313
		<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
   314
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   315
function writeData() {
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   316
  // 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
   317
  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
   318
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   319
  // 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
   320
  if (moreData == null){
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   321
    stream.writeClose();
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   322
  } else{
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   323
    // Wait until write() completes.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   324
    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
   325
      function () {
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   326
        writeData();
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   327
      },
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   328
      function (error) {
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   329
        // Handle error
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   330
      }
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   331
    );
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   332
  }
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   333
}
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   334
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   335
var streamURL = URL.createObjectURL(stream);
8
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
   336
document.getElementById('audioTag').src = streamURL;
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
   337
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   338
writeData();</pre>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   339
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   340
		<p>
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   341
			A producer can also do work only when pulled by using <code>awaitSpaceAvailable()</code>.
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   342
			This method informs the data producing code of that the data consuming API is ready to consume data.
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   343
			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
   344
		</p>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   345
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   346
		<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
   347
  stream.awaitSpaceAvailable().then(
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   348
    function (pulledAmount) {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   349
      stream.write(generateRandomBytes(pulledAmount));
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   350
      poll();
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   351
    }
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   352
  );
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   353
}
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   354
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   355
poll();</pre>
113
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   356
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   357
		<p>
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   358
			The example below demonstrates how the timing to pull new data is determined.
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   359
			When data of cost X is loaded and passed to the Promise, the <a>ReadableStream</a> marks X bytes of pullAmount as used.
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   360
			The next <code>read()</code> call automatically clears the mask to request the data source to produce X more data.
113
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   361
			If precise flow control is needed, you update pullAmount before the next <code>read()</code>.
126
be34c357de7f Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 125
diff changeset
   362
			In the example, the producer API is requested to produce 16 bytes, and then in the fulfill callback, pullAmount is set to the remaining number of bytes not to let the API produce more data.
113
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   363
		</p>
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   364
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   365
		<pre class="example">stream.pullAmount = 16;
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   366
function read() {
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   367
  stream.read().then(
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   368
    function (result) {
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   369
      process(result);
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   370
      stream.pullAmount -= result.size;
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   371
      if (stream.pullAmount == 0) {
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   372
        // Done
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   373
      } else if (stream.eof) {
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   374
        // Done
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   375
      } else {
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   376
        read();
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   377
      }
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   378
    }
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   379
  );
b6a7ebb05e6b Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents: 112
diff changeset
   380
}</pre>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   381
	</section>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   382
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   383
	<section class="section" id="writableByteStream">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   384
		<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
   385
		<p>
128
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   386
			The WritableStream interface defines a protocol for APIs which consume a data stream.
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   387
			The protocol includes:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   388
			<ol>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   389
				<li>How to receive data stream</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   390
				<li>How to notify the writer of completion of writing</li>
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   391
				<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
   392
			</ol>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   393
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   394
			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
   395
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   396
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   397
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   398
			The actual data consumer behind the WritableStream is called a data sink and is identified by <dfn>dataSink</dfn>.
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   399
			A data sink consumes stream of data and notifies the WritableStream of the cost of data the data sink can newly accept.
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   400
			For each data sink, it must be 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
   401
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   402
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   403
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   404
			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
   405
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   406
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   407
		<section class="section">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   408
			<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
   409
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   410
			<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
   411
				<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
   412
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   413
					<p>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   414
						A <a>DOMString</a> that represents the label of an encoding [[!EncodingDetermination]] to be passed to <a>dataSink</a> together with data passed to <code>write()</code> method.
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   415
						It will be used by <a>dataSink</a> for encoding determination.
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   416
						This attribute returns the label last set, or the empty DOMString if never set.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   417
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   418
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   419
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   420
						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
   421
					</section>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   422
				</dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   423
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   424
				<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
   425
				<dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   426
					<p>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   427
						This method writes the specified <var>data</var> to <a>dataSink</a>.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   428
					</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   429
85
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   430
					<section class="note">
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   431
						<p>
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   432
							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
   433
						</p>
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   434
					</section>
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   435
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   436
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   437
						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
   438
						<ol>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   439
							<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
   440
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   441
							<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
   442
132
fc2bc870e7a8 cost argument -> costOverride
Takeshi Yoshino <tyoshino@google.com>
parents: 131
diff changeset
   443
							<li>
fc2bc870e7a8 cost argument -> costOverride
Takeshi Yoshino <tyoshino@google.com>
parents: 131
diff changeset
   444
								If <var>costOverride</var> argument is specified, let <var>amountToWrite</var> be <var>costOverride</var> argument.
fc2bc870e7a8 cost argument -> costOverride
Takeshi Yoshino <tyoshino@google.com>
parents: 131
diff changeset
   445
								Otherwise, let <var>amountToWrite</var> be the <a>cost</a> of <var>data</var>
fc2bc870e7a8 cost argument -> costOverride
Takeshi Yoshino <tyoshino@google.com>
parents: 131
diff changeset
   446
							</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   447
129
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
   448
							<li>Let <var>writePromise</var> be a newly-created <a>Promise</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   449
129
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
   450
							<li>Let <var>pendingWrite</var> be a newly-created <a>PendingWriteDescriptor</a></li>
98
3b89f8cea0fd More tuple -> pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents: 97
diff changeset
   451
							<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
   452
							<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
   453
							<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
   454
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   455
							<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
   456
129
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
   457
							<li>
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
   458
								Run these steps possibly asynchronously:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   459
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   460
								<dl class="switch">
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   461
									<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
   462
									<dd>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   463
										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
   464
										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
   465
									</dd>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   466
									<dt>Otherwise</dt>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   467
									<dd>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   468
										Write <var>data</var> to <a>dataSink</a>.
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   469
									</dd>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   470
								</dl>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   471
							</li>
129
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
   472
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
   473
							<li>Return <var>writePromise</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   474
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   475
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   476
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   477
					<p>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   478
						WritableStream interface doesn't guarantee that <var>data</var> argument is cloned.
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   479
						Modifications made on <var>data</var> argument after <code>write()</code> method call may affect the data written to <a>dataSink</a>.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   480
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   481
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   482
					<dl class="parameters">
111
f3c425cc88db write accepts any data
Takeshi Yoshino <tyoshino@google.com>
parents: 110
diff changeset
   483
						<dt>any data</dt>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   484
						<dd>Data to write.</dd>
132
fc2bc870e7a8 cost argument -> costOverride
Takeshi Yoshino <tyoshino@google.com>
parents: 131
diff changeset
   485
						<dt>optional [Clamp] unsigned long long costOverride</dt>
115
14b1075d41d8 Define cost
Takeshi Yoshino <tyoshino@google.com>
parents: 111
diff changeset
   486
						<dd>Overrides <a>cost</a> of data.</dd>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   487
					</dl>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   488
				</dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   489
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   490
				<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
   491
				<dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   492
					<p>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   493
						This method returns a <a>Promise</a>.
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   494
						The returned Promise will be fulfilled with the data <a>cost</a> which <a>dataSink</a> can accept when <a>dataSink</a> becomes able to accept data with any non-zero amount of cost.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   495
					</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   496
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   497
					<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   498
						This method must run the steps below:
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   499
						<ol>
110
6a7a40bde1e5 Abort wait -> abort waiting
Takeshi Yoshino <tyoshino@google.com>
parents: 109
diff changeset
   500
							<li><a>Abort waiting</a></li>
129
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
   501
							<li>Set <a>waitPromise</a> to a newly-created <a>Promise</a></li>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   502
							<li>Return <a>waitPromise</a></li>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   503
						</ol>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   504
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   505
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   506
103
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   507
				<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
   508
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   509
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   510
						This method tells the WritableStream that no more data will be written to it.
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   511
					</p>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   512
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   513
						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
   514
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   515
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   516
					<p>
103
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   517
						This method must run the steps below:
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   518
						<ol>
129
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
   519
							<li>Let <var>closePromise</var> be a newly-created <a>Promise</a></li>
103
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   520
							<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
   521
							<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
   522
							<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
   523
							<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
   524
						</ol>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   525
					</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   526
				</dd>
116
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   527
118
360cd31579a7 Make reason optional
Takeshi Yoshino <tyoshino@google.com>
parents: 117
diff changeset
   528
				<dt>Promise&amp;lt;undefined&gt; writeAbort(optional any reason)</dt>
116
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   529
				<dd>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   530
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   531
						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
   532
						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
   533
						The interpretation of <var>reason</var> is up to <a>dataSink</a>.
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   534
					</p>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   535
					<p>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   536
						Once this method 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
   537
					</p>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   538
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   539
					<p>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   540
						This method must run the steps below:
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   541
						<ol>
129
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
   542
							<li>Let <var>abortPromise</var> be a newly-created <a>Promise</a></li>
116
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   543
							<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
   544
							<li><a>Write-abort</a> <a>dataSink</a> with <var>reason</var></li>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   545
							<li>Wait until <a>dataSink</a> acknowledges the <a>write-abort</a></li>
116
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   546
							<li>Fulfill <var>abortPromise</var> with <code>undefined</code></li>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   547
						</ol>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   548
					</p>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   549
				</dd>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   550
			</dl>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   551
		</section>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   552
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   553
		<section class="section">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   554
			<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
   555
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   556
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   557
				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
   558
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   559
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   560
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   561
				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
   562
				<ol>
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   563
					<li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   564
						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
   565
					</li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   566
					<li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   567
						Accepts the EOF signal
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   568
					</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   569
					<li>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   570
						Accepts the <dfn>write-abort</dfn> signal with an object parameter named reason.
116
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   571
					</li>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   572
					<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   573
						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
   574
						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
   575
						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
   576
					</li>
103
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   577
					<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   578
						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
   579
						This signal may mean an error.
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   580
						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
   581
					</li>
d59e463a9181 Add writeAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 115
diff changeset
   582
					<li>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   583
						Notifies <a>WritableStream</a> of acknowledgement of the EOF signal.
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   584
					</li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   585
					<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   586
						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
   587
					</li>
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   588
					<li>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   589
						It's defined how to calculate an integer value <dfn>cost</dfn> of each object which the data sink can consume.
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   590
					</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   591
				</ol>
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
		</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   594
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   595
		<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
   596
			<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
   597
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   598
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   599
				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
   600
				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
   601
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   602
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   603
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   604
				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
   605
				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
   606
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   607
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   608
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   609
				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
   610
				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
   611
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   612
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   613
			<p>
110
6a7a40bde1e5 Abort wait -> abort waiting
Takeshi Yoshino <tyoshino@google.com>
parents: 109
diff changeset
   614
				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
   615
				<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   616
					<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
   617
					<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
   618
					<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
   619
					<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
   620
				</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   621
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   622
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   623
			<p>
94
e06bf08768db Formatting data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 93
diff changeset
   624
				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
   625
				<ul>
91
3ed9f08a1f23 Renames for readability
Takeshi Yoshino <tyoshino@google.com>
parents: 90
diff changeset
   626
					<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
   627
					<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
   628
					<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
   629
				</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   630
			</p>
94
e06bf08768db Formatting data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 93
diff changeset
   631
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   632
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   633
				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
   634
				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
   635
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   636
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   637
			<p>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   638
				To <dfn>process pendingWriteQueue</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
   639
				<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   640
					<li>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   641
						While <a>pendingWriteQueue</a> is not empty, repeat the steps below:
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   642
						<ol>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   643
							<li>Let <var>pendingWrite</var> be the head element of <a>pendingWriteQueue</a></li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   644
							<li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   645
								<dl class="switch">
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   646
									<dt>If <a>sinkGone</a> is set</dt>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   647
									<dd>
119
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   648
										<ol>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   649
											<li>Pop <var>pendingWrite</var> from <a>pendingWriteQueue</a>, and then</li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   650
											<li>If <var>pendingWrite.promise</var> is not <code>null</code>, reject it with <a>sinkErrorDetail</a></li>
119
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   651
										</ol>
127
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   652
									</dd>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   653
									<dt>Otherwise</dt>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   654
									<dd>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   655
										<ol>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   656
											<li>Let <var>amountToAcknowledge</var> be min(<var>pendingWrite.amount</var> - <var>pendingWrite.ackedAmount</var>, <a>spaceAvailable</a>)</li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   657
											<li>Set <a>spaceAvailable</a> to <a>spaceAvailable</a> - <var>amountToAcknowledge</var></li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   658
											<li>Set <var>pendingWrite.ackedAmount</var> to <var>pendingWrite.ackedAmount</var> + <var>amountToAcknowledge</var></li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   659
											<li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   660
												<dl class="switch">
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   661
													<dt>If <var>pendingWrite.ackedAmount</var> equals to <var>pendingWrite.amount</var></dt>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   662
													<dd>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   663
														<ol>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   664
															<li>Pop <var>pendingWrite</var> from <a>pendingWriteQueue</a></li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   665
															<li>If <var>pendingWrite.promise</var> is not <code>null</code>, fulfill it with <var>pendingWrite.amount</var></li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   666
														</ol>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   667
													</dd>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   668
													<dt>Otherwise</dt>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   669
													<dd>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   670
														Exit from this loop
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   671
													</dd>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   672
												</dl>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   673
											</li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   674
										</ol>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   675
									</dd>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   676
								</dl>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   677
							</li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   678
						</ol>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   679
					</li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   680
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   681
					<li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   682
						If <a>pendingWriteQueue</a> is empty and <a>spaceAvailable</a> is not 0, run the steps below:
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   683
						<ol>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   684
							<li>If <a>waitPromise</a> is <code>null</code>, terminate these steps</li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   685
							<li>Let <var>detachedWaitPromise</var> be <a>waitPromise</a></li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   686
							<li>Set <a>waitPromise</a> to <code>null</code></li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   687
							<li>Fulfill <var>detachedWaitPromise</var> with <a>spaceAvailable</a></li>
bf65397910b7 More rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 126
diff changeset
   688
						</ol>
119
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   689
					</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   690
				</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   691
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   692
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   693
			<p>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   694
				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
   695
				<ol>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   696
					<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
   697
					<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
   698
				</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   699
			</p>
119
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   700
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   701
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   702
				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
   703
			</p>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   704
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   705
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   706
				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
   707
			</p>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   708
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   709
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   710
				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
   711
				<ol>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   712
					<li>Set <a>sinkGone</a></li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   713
					<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
   714
					<li><a>Process pendingWriteQueue</a></li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   715
				</ol>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
   716
			</p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   717
		</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   718
	</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   719
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   720
	<section class="section" id="readableByteStream">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   721
		<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
   722
		<p>
128
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   723
			The ReadableStream interface defines a protocol for APIs which produce a data stream.
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   724
			This protocol includes:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   725
			<ol>
128
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   726
				<li>How to receive a read request from the reader and pass output data to the reader</li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   727
				<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
   728
				<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
   729
			</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   730
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   731
			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
   732
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   733
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   734
		<p>
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   735
			Interfaces introduced in this section provide simple and convenient ways to consume data.
128
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   736
			They connect arbitrary data stream producer and data consuming 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
   737
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   738
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   739
		<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   740
			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>.
128
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   741
			A data source, however, can have a one-to-many relationship with ReadableStreams, 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
   742
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   743
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   744
		<section class="section" id="readableByteStreamInterface">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   745
			<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
   746
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   747
			<dl class="idl" title="interface ReadableStream">
125
98448480356b ByteStreamReadType -> StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents: 124
diff changeset
   748
				<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
   749
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   750
					<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
   751
						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
   752
						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
   753
						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
   754
					</p>
128
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   755
					<p>
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   756
						This attribute works only when the data to be read from the ReadableStream represents binary data.
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   757
					</p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   758
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   759
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   760
				<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
   761
				<dd>
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
						Specifies a <a>DOMString</a> that represents the label of an encoding [[!EncodingDetermination]].
128
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   764
						If set, it will be used as part of the encoding determination used when processing a <code>read()</code> and <code>readUpTo()</code> method call.
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   765
					</p>
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   766
					<p>
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   767
						This attribute works only when the data to be read from the ReadableStream represents binary data.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   768
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   769
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   770
					<section class="note">
128
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   771
						This parameter is not designed to be specified as an argument of the reading methods since it's not likely to be changed frequently.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   772
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   773
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   774
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   775
				<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
   776
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   777
					<p>
128
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   778
						This attribute provides the ReadableStream with a hint of how much data the reader can consume currently.
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   779
						Each implementation of the 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
   780
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   781
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   782
					<p>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   783
						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
   784
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   785
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   786
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   787
						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
   788
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   789
					<section class="note">
128
56491a744f4d ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents: 127
diff changeset
   790
						It's possible that the cost of data received by <code>read()</code> is more than the pullAmount value.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   791
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   792
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   793
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   794
				<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
   795
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   796
					<p>
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   797
						This method reads binary data from the ReadableStream.
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   798
						The returned <a>Promise</a> is fulfilled when any of the following conditions is met:
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   799
						<ul>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   800
							<li>The total size of produced bytes becomes equal to <var></var></li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   801
							<li>The EOF is reached</li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   802
						</ul>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   803
						The <a>cost</a> of data returned by this method can be less than <var>size</var> when data cannot be fully converted into the type specified by <a href="#widl-ReadableStream-readBinaryAs">readBinaryAs</a> or the EOF is reached.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   804
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   805
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   806
					<p>
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   807
						This method must run these steps:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   808
						<ol>
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   809
							<li>If <a href="#widl-ReadableStream-readBinaryAs">readBinaryAs</a> is "<code>as-is</code>", return a <a>Promise</a> rejected with 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
   810
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   811
							<li>If <a>pendingRead</a> is not <code>null</code>, return a <a>Promise</a> rejected with an "<code><a>InvalidStateError</a></code>"</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   812
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   813
							<li>Set <a>pendingRead</a> to a newly-created <a>PendingReadDescriptor</a></li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   814
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   815
							<li>Set <a>pendingRead</a>.<var>binaryAs</var> to the current value of <a href="#widl-ReadableStream-readBinaryAs">readBinaryAs</a></li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   816
							<li>Set <a>pendingRead</a>.<var>encoding</var> to the current value of <a href="#widl-ReadableStream-readEncoding">readEncoding</a></li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   817
							<li>Set <a>pendingRead</a>.<var>size</var> to <var>size</var></li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   818
							<li>Set <a>pendingRead</a>.<var>promise</var> to a newly-created <a>Promise</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   819
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
   820
							<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
   821
							<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
   822
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   823
							<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
   824
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   825
							<li>Return <a>pendingRead</a>.<var>promise</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   826
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   827
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   828
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   829
					<dl class="parameters">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   830
						<dt>[Clamp] unsigned long long size</dt>
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   831
						<dd>Upper limit of total cost of data to be read</dd>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   832
					</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   833
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   834
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   835
						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
   836
						<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   837
							<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
   838
							<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
   839
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   840
					</section>
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
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   843
				<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
   844
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   845
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   846
						This method reads data from the ReadableStream.
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   847
						The speed of reading can be roughly adjusted by using <a href="#widl-StreamReadResult-pullAmount">pullAmount</a>.
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   848
						<a href="#widl-StreamReadResult-pullAmount">pullAmount</a> doesn't necessarily limit the size of data being read by this method.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   849
					</p>
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
					<p>
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   852
						This method must run these steps:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   853
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   854
						<ol>
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   855
							<li>If <a>pendingRead</a> is not <code>null</code>, return a Promise reject with an "<code><a>InvalidStateError</a></code>"</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   856
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   857
							<li>Set <a>pendingRead</a> to a newly-created <a>PendingReadDescriptor</a></li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   858
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   859
							<li>Set <a>pendingRead</a>.<var>binaryAs</var> to the current value of <a href="#widl-ReadableStream-readBinaryAs">readBinaryAs</a></li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   860
							<li>Set <a>pendingRead</a>.<var>encoding</var> to the current value of <a href="#widl-ReadableStream-readEncoding">readEncoding</a></li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   861
							<li>Set <a>pendingRead</a>.<var>size</var> to <code>undefined</code></li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   862
							<li>Set <a>pendingRead</a>.<var>promise</var> to a newly-created <a>Promise</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   863
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   864
							<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
   865
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   866
							<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
   867
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
   868
							<li>Return <a>pendingRead</a>.<var>promise</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   869
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   870
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   871
78
12c164bee09f Add diagrams
Takeshi Yoshino <tyoshino@google.com>
parents: 77
diff changeset
   872
					<p>
83
afed6501a898 moved images, fixed typos, fixed header
fmoussa <feras.moussa@hotmail.com>
parents: 81
diff changeset
   873
						<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
   874
					</p>
12c164bee09f Add diagrams
Takeshi Yoshino <tyoshino@google.com>
parents: 77
diff changeset
   875
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   876
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   877
						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
   878
						<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   879
							<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
   880
							<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
   881
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   882
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   883
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   884
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
   885
				<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
   886
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   887
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   888
						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
   889
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   890
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   891
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   892
						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
   893
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   894
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   895
					<section class="note">
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   896
						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
   897
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   898
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   899
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   900
						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
   901
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   902
						<ol>
130
e8f1ead18653 Throw -> return a Promise rejected with
Takeshi Yoshino <tyoshino@google.com>
parents: 129
diff changeset
   903
							<li>If <a>readPending</a> is set, return a <a>Promise</a> rejected with an "<code><a>InvalidStateError</a></code>"</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   904
							<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
   905
110
6a7a40bde1e5 Abort wait -> abort waiting
Takeshi Yoshino <tyoshino@google.com>
parents: 109
diff changeset
   906
							<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
   907
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   908
							<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
   909
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   910
							<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
   911
129
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
   912
							<li>Let <var>pipePromise</var> be a newly-created <a>Promise</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   913
							<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
   914
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   915
							<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
   916
							<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   917
								Repeat the steps below:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   918
								<ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   919
									<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   920
										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
   921
										<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   922
											<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
   923
											<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
   924
											<dt>Otherwise</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   925
											<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
   926
										</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   927
										<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
   928
											<li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   929
												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
   930
												<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
   931
													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
   932
												</section>
7421b9a22a7e More bug fix in pipe(). numBytesRequested is used where numBytesSpaceAvailable must be used.
Takeshi Yoshino <tyoshino@google.com>
parents: 99
diff changeset
   933
											</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   934
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   935
												<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   936
													<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
   937
													<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
   938
													<dt>Otherwise</dt>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   939
													<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
   940
												</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   941
											</li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   942
											<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
   943
											<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
   944
129
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
   945
											<li>Let <var>pendingWrite</var> be a newly-created <a>PendingWriteDescriptor</a></li>
98
3b89f8cea0fd More tuple -> pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents: 97
diff changeset
   946
											<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
   947
											<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
   948
											<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
   949
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   950
											<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
   951
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   952
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   953
												<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   954
													<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
   955
													<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
   956
													<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
   957
													<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
   958
												</dl>
102
a176607d4c3a TODO about pipe() finish timing
Takeshi Yoshino <tyoshino@google.com>
parents: 101
diff changeset
   959
												<section class="note">
a176607d4c3a TODO about pipe() finish timing
Takeshi Yoshino <tyoshino@google.com>
parents: 101
diff changeset
   960
													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
   961
												</section>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   962
											</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   963
										</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   964
									</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   965
									<li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   966
										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
   967
										<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   968
											<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
   969
											<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
   970
											<dt>Otherwise</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   971
											<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
   972
										</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   973
										<ol>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   974
											<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
   975
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   976
												<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   977
													<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
   978
													<dd>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   979
														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
   980
														<section class="note">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   981
															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
   982
															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
   983
														</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   984
														<section class="note">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
   985
															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
   986
														</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   987
													</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   988
													<dt>Otherwise</dt>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   989
													<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
   990
												</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   991
											</li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   992
											<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
   993
											<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
   994
										</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   995
									</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   996
								</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   997
							</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   998
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   999
							<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
  1000
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1001
							<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
  1002
129
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
  1003
							<li>Let <var>result</var> be a newly-created <a>StreamReadResult</a></li>
124
9dc273a030cc - ByteStreamReadResult -> StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents: 123
diff changeset
  1004
							<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
  1005
							<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
  1006
							<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
  1007
							<li>
101
7da4a886ff9f More pipe() bug fixes
Takeshi Yoshino <tyoshino@google.com>
parents: 100
diff changeset
  1008
								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
  1009
								<section class="note">
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1010
									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
  1011
								</section>
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
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1014
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1015
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1016
					<dl class="parameters">
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1017
						<dt>WritableStream destination</dt>
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1018
						<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
  1019
						<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
  1020
						<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
  1021
					</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1022
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1023
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1024
				<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
  1025
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1026
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1027
						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
  1028
						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
  1029
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1030
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1031
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1032
						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
  1033
						<ol>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1034
							<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
  1035
							<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
  1036
							<li>Return <var>branch</var>.</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1037
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1038
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1039
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1040
118
360cd31579a7 Make reason optional
Takeshi Yoshino <tyoshino@google.com>
parents: 117
diff changeset
  1041
				<dt>Promise&amp;lt;undefined&gt; readAbort(optional any reason)</dt>
117
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1042
				<dd>
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1043
					<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1044
						This method tells the ReadableStream that no more data will be read from it optionally with indication of error.
117
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1045
						The details of the error will be given by <var>reason</var> argument.
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1046
						The interpretation of <var>reason</var> is up to <a>dataSource</a>.
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1047
						Once readAbort() has been called on a ReadableStream, no further method calls can be made on the ReadableStream.
117
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1048
					</p>
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1049
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1050
					<p>
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1051
						This method must run the steps below:
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1052
						<ol>
129
855e24afba79 - new -> newly-create
Takeshi Yoshino <tyoshino@google.com>
parents: 128
diff changeset
  1053
							<li>Let <var>abortPromise</var> be a newly-created <a>Promise</a></li>
133
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
  1054
							<li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
  1055
								Run these steps asynchronously:
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
  1056
								<ol>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
  1057
									<li><a>Read-abort</a> <a>dataSource</a> with <var>reason</var></li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
  1058
									<li>Wait until <a>dataSource</a> acknowledges the read-abort</li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
  1059
									<li>Fulfill <var>abortPromise</var> with <code>undefined</code></li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
  1060
								</ol>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
  1061
							</li>
ecde9f975249 Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 132
diff changeset
  1062
							<li>Return <var>abortPromise</var></li>
117
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1063
						</ol>
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1064
					</p>
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1065
				</dd>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
  1066
			</dl>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
  1067
		</section>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
  1068
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1069
		<section class="section" id='readableByteStreamDataSource'>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1070
			<h3>Data source model</h3>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1071
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1072
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1073
				A data source produces the bytes to be consumed via the <a>ReadableStream</a> interface instances.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1074
				A <a>ReadableStream</a> retrieves bytes from an associated data source.
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1075
				The data source model is not directly surfaced in the API, and is described here to provide details on how internal operations such as <a href="#widl-ReadableStream-fork-ReadableStream">fork()</a> can be handled.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1076
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1077
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1078
			<p>
95
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1079
				A <dfn>data source</dfn> can be anything that:
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1080
				<ul>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1081
					<li>
120
1eab5673997f Break at the end of a sentence
Takeshi Yoshino <tyoshino@google.com>
parents: 114
diff changeset
  1082
						Produces bytes.
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1083
						Newly produced bytes will be delivered to the associated <a>ReadableStream</a>.
95
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1084
					</li>
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1085
					<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1086
						Notifies <a>ReadableStream</a> of the EOF signal.
119
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
  1087
						This signal may mean an error.
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
  1088
						If it means an error, an object indicating the details of the error is attached.
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
  1089
					</li>
218f3b3a2df5 Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents: 118
diff changeset
  1090
					<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1091
						Accepts requests for production of bytes from a <a>ReadableStream</a>.
120
1eab5673997f Break at the end of a sentence
Takeshi Yoshino <tyoshino@google.com>
parents: 114
diff changeset
  1092
						A byte production request consists of an integer indicating the number of bytes to produce in addition to already requested ones.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1093
						Interpretation of the request is up to data sources.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1094
						Data sources may respond to retrieval requests with data larger than requested.
95
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1095
						Requests and delivery of bytes don't need to 1-to-1 correspond.
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1096
						Data sources may produce bytes and send to <a>ReadableStream</a> unsolicitedly without receiving any retrieval request.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1097
					</li>
104
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
  1098
					<li>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1099
						Accepts and acknowledges read-abort signal which means the associated <a>ReadableStream</a> has completed consuming bytes from this data source optionally with indication of any error.
117
6ccb7d75a511 Add readAbort
Takeshi Yoshino <tyoshino@google.com>
parents: 116
diff changeset
  1100
					</li>
95
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1101
				</ul>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1102
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1103
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1104
			<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1105
				To allow multiple consumers, we use a wrapper <dfn>data source wrapper</dfn> for range reference counting on produced bytes.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1106
				A <a>data source wrapper</a> has the following functionalities:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1107
				<ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1108
					<li>has a <var>queue</var> to which newly produced bytes are pushed</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1109
					<li>has a sorted map <dfn>cursorMap</dfn> whose key is reader ID and value is integer called cursor</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1110
					<li>can issue reader IDs which are unique to the <a>data source wrapper</a> instance when requested</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1111
					<li>pops bytes from <var>queue</var> when the smallest cursor in <a>cursorMap</a> by the difference of the new smallest cursor and the old smallest cursor</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1112
					<li>when there's not sufficient bytes in <var>queue</var> to respond to coming retrieval request, retrieves bytes from the wrapped data source</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1113
				</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1114
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1115
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1116
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1117
				When <a href="#widl-ReadableStream-fork-ReadableStream">fork()</a> is called, a new reader is registered to the original <a>ReadableStream</a>'s data source and the new <a>ReadableStream</a> uses read() method to fetch data from it.
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1118
			</p>
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1119
		</section>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1120
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1121
		<section class="section" id="interactingWithDataSource">
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1122
			<h2>Interacting with the data source</h2>
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1123
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1124
			<section class="note">
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1125
				This interface is designed to work even if operations on <a>dataSource</a> are asynchronous.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1126
				If <a>dataSource</a> is synchronously accessible, some of the algorithms can be simplified.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1127
			</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1128
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1129
			<p>
123
2c23cbb3665f Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents: 122
diff changeset
  1130
				A ReadableStream has an associated <a>data source</a> referred by <dfn>dataSource</dfn> from which the ReadableStream retrieves bytes.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.m&