Overview.htm
author Takeshi Yoshino <tyoshino@google.com>
Mon, 09 Dec 2013 23:16:26 +0900
changeset 110 6a7a40bde1e5
parent 109 44cada6acb2f
child 111 f3c425cc88db
permissions -rw-r--r--
Abort wait -> abort waiting
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>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   122
			This specification provides an API for representing a byte stream 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>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   127
				An interface named <a>WritableByteStream</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>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   130
				An interface named <a>ReadableByteStream</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>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   133
				An interface named <a>ByteStream</a> which inherits both WritableByteStream and ReadableByteStream and represents a byte sequence.
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>
99
b3b8bbde934f Teminology: Tuple -> struct type
Takeshi Yoshino <tyoshino@google.com>
parents: 98
diff changeset
   136
				A struct type named <a>ByteStreamReadResult</a> which represents the result of consuming operations such as <code>read()</code> and <code>pipe()</code>.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   137
				It holds a chunk of content read from a <a>ReadableByteStream</a>, the number of bytes consumed, and EOF signal.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   138
			</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   139
			<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   140
				An enum <a>ByteStreamReadType</a> which represents data types as which data can be read from a <a>ReadableByteStream</a>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   141
			</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   142
			<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   143
				A list of notable byte stream <a href="#producers">producers</a> and <a href="#consumers">consumers</a> for which we can apply either or both of <a>ReadableByteStream</a> and <a>WritableByteStream</a> model.
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>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   146
				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>WritableByteStream</a> and downloading a response as a <a>ReadableByteStream</a>.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   147
			</li>
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   148
			<li>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   149
				Extensions to <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-createObjectURL">URL.createObjectURL</a> and
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   150
				<a href="http://dev.w3.org/2006/webapi/FileAPI/#dfn-revokeObjectURL">URL.revokeObjectURL</a> to add support for <a>ReadableByteStream</a>.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   151
			</li>
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   152
		</ul>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   153
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   154
		<p>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   155
			This API is designed to be used in conjunction with other APIs and elements on the web platform, notably:
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   156
			<a href="http://dev.w3.org/2006/webapi/FileAPI">File</a> [[!FILE-API]],
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   157
			<a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2">XMLHttpRequest</a>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   158
			(e.g. with an overloaded <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-send-method"><code>send()</code></a> method
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   159
			and <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-responsetype-attribute"><code>response</code></a> object for <a>ReadableByteStream</a> objects) [[!XMLHTTPREQUEST2]],
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   160
			<a href="http://dev.w3.org/html5/postmsg/#dom-window-postmessage"><code>postMessage</code></a>, and
8
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
   161
			Web Workers [[!WEBWORKERS]].
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   162
		</p>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   163
	</section>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   164
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   165
	<section id="introduction" class="section informative">
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   166
		<h2>Introduction</h2>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   167
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   168
		<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   169
			Web applications should have the ability to acquire, manipulate, and pass data in a wide variety of forms, including as a sequence of data made available over time.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   170
			This specification defines the basic representation for byte streams, and programmatic ways to read and write streams of data and errors raised on those operations.
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   171
		</p>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   172
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   173
		<p>
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   174
			The <a>WritableByteStream</a> interface defines a general protocol for <a href="#consumers">data consuming APIs</a> to communicate with data producing code.
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   175
			In these cases, the data consuming API, such as a decoder, provides a <a>WritableByteStream</a> for other applications to write to, enabling the decoder to begin decoding data as it becomes available.
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   176
			The data is written to the internal data sink of a data consuming API using:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   177
			<ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   178
				<li>The <code>write()</code> method for writing bytes to the data sink as a <a>ArrayBufferView</a>, <a>DOMString</a> or <a>Blob</a></li>
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   179
				<li>
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   180
					The <code>awaitSpaceAvailable()</code> method for allowing a data-producer to write to the data sink only when the data sink specifies it is now available to consume more data.
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   181
					This is useful for cases where an app may want to avoid backpressure and filling the internal buffer.
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   182
				</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   183
			</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   184
			Actual transfer of bytes to the data sink may happen either synchronously or asynchronously.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   185
			<a>WritableByteStream</a> hides the details of actual communication with the data sink while allowing for an efficient transfer of bytes.
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   186
		</p>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   187
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   188
		<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   189
			The <a>ReadableByteStream</a> interface defines a general protocol for <a href="#producers">data producing APIs</a> to communicate with data consuming code.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   190
			This interface represents the potential for an infinite amount of bytes which are obtained over time and read once.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   191
			Data consuming code reads data from the data source inside a data producing API using:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   192
			<ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   193
				<li>The <code>read()</code> and <code>readExact()</code> methods for reading bytes from the data source as a <a>ArrayBufferView</a>, <a>DOMString</a> or <a>Blob</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   194
				<li>The <code>pullAmount</code> attribute to pace data retrieval from the data source</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   195
				<li>The <code>pipe()</code> method for transferring data in bulk from the data source into the data sink of a <a>WritableByteStream</a> from another API</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   196
			</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   197
			Actual transfer of bytes from the data source may happen either synchronously or asynchronously.
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   198
			The <a>ReadableByteStream</a> hides the details of actual communication with the data source while allowing for an efficient transfer of bytes.
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   199
		</p>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   200
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   201
		<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   202
			With the combination of the following features, this interface suite responds to various simple and complex needs of byte stream handling.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   203
			<ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   204
				<li>Delayed notification of completion by using <a>Promise</a>s</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   205
				<li>Explicit back pressure management by propagating room for consumption back to producers</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   206
				<li><a>WritableByteStream</a> always accepts incoming data synchronously</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   207
			</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   208
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   209
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   210
		<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   211
			The <a>ByteStream</a> is a simple implementation of both the <a>WritableByteStream</a> and <a>ReadableByteStream</a> interface.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   212
			A ByteStream has a single queue of bytes and it works as a data sink for the WritableByteStream interface and as a data source for the ReadableByteStream interface.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   213
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   214
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   215
		<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   216
			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
   217
			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
   218
			Error conditions that may arise during an operation will be handled by the reject callback set to the Promise.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   219
			An example will be illustrative.
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   220
		</p>
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   221
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   222
		<p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   223
			In the example below, different code blocks handle progress, error, and success conditions.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   224
			The example demonstrates how to read a chunk of data from a <a>ReadableByteStream</a> using <code>read()</code>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   225
			The <a>ReadableByteStream</a> may of come from a <a href="#producers">producer</a> such as <code>XMLHttpRequest</code>.
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   226
			Additionally, it demonstrates how to read bytes from a <a>ReadableByteStream</a> until an EOF is encountered.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   227
		</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   228
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   229
		<pre class="example">
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   230
// Tell stream that we're ready to consume 1024 bytes.
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   231
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
   232
stream.readEncoding = "UTF-8";
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   233
stream.readType = "arraybuffer";
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   234
stream.read().then(
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   235
  function (result) {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   236
    // Process data
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   237
  },
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   238
  function (error) {
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   239
    // Handle error
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   240
  });</pre>
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   241
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   242
		<pre class="example">// Read data from the ReadableByteStream repeatedly
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   243
function readUntilEof() {
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   244
  stream.read().then(
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   245
    function (result) {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   246
      processData(result.data);
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   247
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   248
      if (!result.eof) {
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   249
        readUntilEof();
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   250
      }
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   251
    },
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   252
    function (error) {
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   253
      // Handle error
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   254
    });
8
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
   255
}
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   256
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   257
readUntilEof();</pre>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   258
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   259
		<p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   260
			In the example below, different code blocks handle progress, error, and success conditions.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   261
			The example below demonstrates how to obtain a <a>ReadableByteStream</a> from <a>XMLHttpRequest</a> to begin playing a large video in <code>readystate</code> LOADING.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   262
			The example takes the <a>ReadableByteStream</a> from a <a href="#producers">producer</a>, <a>XMLHttpRequest</a>, and gives it to a <a href="#consumers">consumer</a>, the video tag.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   263
		</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   264
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   265
		<pre class="example">function handler() {
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   266
  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
   267
    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
   268
    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
   269
    document.getElementById("myVideoTag").src = streamURL;
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   270
  }
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   271
}
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   272
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   273
var client = new XMLHttpRequest();
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   274
client.onreadystatechange = handler;
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   275
client.setRequestHeader('customHeader', 'value');
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   276
client.setRequestHeader('customHeader2', 'value2');
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   277
client.open("GET", "myvideo.h264");
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   278
client.responseType = "stream";
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   279
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
   280
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   281
		<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   282
			In addition to the <a>ReadableByteStream</a> interface, this specification introduces an interface called <a>WritableByteStream</a> for data consuming APIs.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   283
			The <a>WritableByteStream</a> interface provides a <code>write()</code> method which allows applications to write data to a <a href="#consumers">data consuming API</a>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   284
			<code>write()</code> supports writing bytes represented as a <a>Blob</a>, <a>ArrayBuffer</a>, or <a>DOMString</a>.
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   285
		</p>
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   286
		<p>
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   287
			The example below demonstrates how to use <code>write()</code> to load a <a>ReadableByteStream</a> into the audio tag, whose data could be processed and built dynamically at read time.
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   288
			ByteStream in the example is a class which implements both <a>WritableByteStream</a> and <a>ReadableByteStream</a>.
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   289
			It accepts bytes generated by the code via <a>WritableByteStream</a> methods, and the written data will be consumed by the audio element via the object URL which is a part of <a>ReadableByteStream</a>'s functionality.
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   290
		</p>
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   291
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   292
		<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
   293
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   294
function writeData() {
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   295
  // 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
   296
  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
   297
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   298
  // 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
   299
  if (moreData == null){
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   300
    stream.writeClose();
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   301
  } else{
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   302
    // Wait until write() completes.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   303
    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
   304
      function () {
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   305
        writeData();
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   306
      },
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   307
      function (error) {
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   308
        // Handle error
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   309
      }
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   310
    );
0
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   311
  }
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   312
}
af7713ef49dc Adding Editors Draft
eliotgra@ELIOTGRA-X220.redmond.corp.microsoft.com
parents:
diff changeset
   313
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   314
var streamURL = URL.createObjectURL(stream);
8
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
   315
document.getElementById('audioTag').src = streamURL;
cb4e62ad9587 Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents: 7
diff changeset
   316
24
01eb488cd8c4 Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents: 23
diff changeset
   317
writeData();</pre>
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
		<p>
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   320
			A producer can also do work only when pulled by using <code>awaitSpaceAvailable()</code>, which will inform the producer when to produce data.
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   321
			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
   322
		</p>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   323
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   324
		<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
   325
  stream.awaitSpaceAvailable().then(
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   326
    function (pulledAmount) {
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   327
      stream.write(generateRandomBytes(pulledAmount));
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   328
      poll();
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   329
    }
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   330
  );
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   331
}
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   332
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   333
poll();</pre>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   334
	</section>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   335
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   336
	<section class="section" id="writableByteStream">
81
a448e7c65411 Fix typo
Takeshi Yoshino <tyoshino@google.com>
parents: 79
diff changeset
   337
		<h2>WritableByteStream Interface</h2>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   338
		<p>
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   339
			The WritableByteStream interface defines a protocol for APIs which consume byte streams.
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   340
			The protocol includes:
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   341
			<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   342
				<li>How to receive the byte stream</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   343
				<li>How to notify the writer of completion of writing</li>
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   344
				<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
   345
			</ol>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   346
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   347
			By returning a <a>Promise</a> and delaying fulfillment of it, the WritableByteStream realizes flow control.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   348
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   349
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   350
		<p>
88
ef2c58cd8563 Rephrased dataSink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 87
diff changeset
   351
			The actual data consumer behind the WritableByteStream is called a data sink and is identified by <dfn>dataSink</dfn>.
ef2c58cd8563 Rephrased dataSink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 87
diff changeset
   352
			A data sink consumes byte streams and notifies the WritableByteStream of the number of bytes the data sink can newly accept.
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   353
			For each data sink, it's defined how to calculate <a>cost</a> of each object which the data sink can consume.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   354
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   355
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   356
		<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   357
			A WritableByteStream 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>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   358
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   359
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   360
		<section class="section">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   361
			<h3>WritableByteStream interface</h3>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   362
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   363
			<dl class="idl" title="interface WritableByteStream">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   364
				<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
   365
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   366
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   367
						Specifies a <a>DOMString</a> that represents the label of an encoding [[!EncodingDetermination]].
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   368
						If set, it will be used as part of the encoding determination used when processing a <a>DOMString</a> provided in a <code>write()</code> method call.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   369
						It will return the label last set, or the empty DOMString if never set.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   370
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   371
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   372
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   373
						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
   374
					</section>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   375
				</dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   376
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   377
				<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
   378
				<dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   379
					<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   380
						This method writes the specified <var>data</var> to the WritableByteStream.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   381
					</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   382
85
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   383
					<section class="note">
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   384
						<p>
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   385
							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
   386
						</p>
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   387
					</section>
885937bdcc17 Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents: 84
diff changeset
   388
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   389
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   390
						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
   391
						<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   392
							<li>Let <var>latchedEncoding</var> be the current value of <a href="#widl-WritableByteStream-writeEncoding">writeEncoding</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   393
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   394
							<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
   395
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   396
							<li>Let <var>amountToWrite</var> be the <a>cost</a> of <var>data</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   397
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   398
							<li>Let <var>writePromise</var> be a new <a>Promise</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   399
98
3b89f8cea0fd More tuple -> pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents: 97
diff changeset
   400
							<li>Let <var>pendingWrite</var> be a new <a>PendingWriteDescriptor</a></li>
3b89f8cea0fd More tuple -> pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents: 97
diff changeset
   401
							<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
   402
							<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
   403
							<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
   404
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   405
							<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
   406
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   407
							<li>Return <var>writePromise</var>, and then continue to process the steps in this algorithm</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   408
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   409
							<li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   410
								<dl class="switch">
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   411
									<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
   412
									<dd>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   413
										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
   414
										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
   415
									</dd>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   416
									<dt>Otherwise</dt>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   417
									<dd>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   418
										Write <var>data</var> to <a>dataSink</a>.
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   419
									</dd>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   420
								</dl>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   421
								Write <var>bytesToWrite</var> to <a>dataSink</a>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   422
							</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   423
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   424
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   425
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   426
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   427
						If <var>data</var> argument is an <a>ArrayBufferView</a>, modifications made on the ArrayBufferView's contents between <code>write()</code> method call and fulfill of the returned Promise may affect the data written to <a>dataSink</a>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   428
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   429
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   430
					<dl class="parameters">
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   431
						<dt>(DOMString or ArrayBufferView or Blob) data</dt>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   432
						<dd>Data to write.</dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   433
					</dl>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   434
				</dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
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
				<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
   437
				<dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   438
					<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   439
						This method waits until the WritableByteStream becomes able to accept any non-zero amount of data.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   440
						The returned <a>Promise</a> will be fulfilled with the number of bytes the WritableByteStream can accept.
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   441
					</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   442
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   443
					<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   444
						This method must run the steps below:
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   445
						<ol>
110
6a7a40bde1e5 Abort wait -> abort waiting
Takeshi Yoshino <tyoshino@google.com>
parents: 109
diff changeset
   446
							<li><a>Abort waiting</a></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   447
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   448
							<li>Set <a>waitPromise</a> to a new <a>Promise</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   449
							<li>Return <a>waitPromise</a>, and then continue to process the steps in this algorithm</li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   450
							<li>Wait until <a>pendingWriteQueue</a> is empty and <a>spaceAvailable</a> is not 0</li>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   451
							<li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   452
								Queue a task to run the steps below:
38
3cdd8b2d21d9 Merging changes made for preparing WD
Takeshi Yoshino <tyoshino@google.com>
parents: 37
diff changeset
   453
								<ol>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   454
									<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
   455
									<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
   456
									<li>Set <a>waitPromise</a> to <code>null</code></li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   457
									<li>Fulfill <var>detachedWaitPromise</var> with <a>spaceAvailable</a></li>
38
3cdd8b2d21d9 Merging changes made for preparing WD
Takeshi Yoshino <tyoshino@google.com>
parents: 37
diff changeset
   458
								</ol>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   459
							</li>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   460
						</ol>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   461
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   462
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   463
103
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   464
				<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
   465
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   466
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   467
						This method tells the WritableByteStream that no more data will be written to it.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   468
						Once writeClose() has been called on a WritableByteStream, no further method calls can be made on the WritableByteStream.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   469
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   470
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   471
					<p>
103
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   472
						This method must run the steps below:
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   473
						<ol>
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   474
							<li>Let <var>closePromise</var> be a new <a>Promise</a></li>
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   475
							<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
   476
							<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
   477
							<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
   478
							<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
   479
						</ol>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   480
					</p>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   481
				</dd>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   482
			</dl>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   483
		</section>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
   484
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   485
		<section class="section">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   486
			<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
   487
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   488
			<p>
79
548c5e39ff07 Renaming variables and one grammar fix
Takeshi Yoshino <tyoshino@google.com>
parents: 78
diff changeset
   489
				The data sink is the underlying mechanism which a <a>WritableByteStream</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
   490
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   491
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   492
			<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   493
				A data sink to which the <a>WritableByteStream</a> interface writes bytes can be anything which:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   494
				<ol>
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   495
					<li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   496
						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
   497
					</li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   498
					<li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   499
						Accepts the EOF signal
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   500
					</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   501
					<li>
103
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   502
						Notifies <a>WritableByteStream</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
   503
						When and how to generate such notifications is up to data sinks.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   504
						Data sinks must be able to accept data more than it notified <a>WritableByteStream</a> of.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   505
					</li>
103
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   506
					<li>
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   507
						Notifies <a>WritableByteStream</a> of acknowledgement of the EOF.
56c80502bb30 Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 102
diff changeset
   508
					</li>
109
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   509
					<li>
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   510
						How to calculate an integer value <dfn>cost</dfn> of each object which the data sink can consume.
44cada6acb2f Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents: 108
diff changeset
   511
					</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   512
				</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   513
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   514
		</section>
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
		<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
   517
			<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
   518
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   519
			<p>
93
33fa9ecdbe74 A bit tweak on data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 92
diff changeset
   520
				This section defines the internal mechanisms for how the WritableByteStream interacts with <a>dataSink</a>.
33fa9ecdbe74 A bit tweak on data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 92
diff changeset
   521
				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
   522
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   523
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   524
			<p>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   525
				A WritableByteStream 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
   526
				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
   527
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   528
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   529
			<p>
86
d1e43b22a73d Complement waitPromise definition sentence
Takeshi Yoshino <tyoshino@google.com>
parents: 85
diff changeset
   530
				A WritableByteStream 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
   531
				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
   532
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   533
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   534
			<p>
110
6a7a40bde1e5 Abort wait -> abort waiting
Takeshi Yoshino <tyoshino@google.com>
parents: 109
diff changeset
   535
				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
   536
				<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   537
					<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
   538
					<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
   539
					<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
   540
					<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
   541
				</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   542
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   543
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   544
			<p>
94
e06bf08768db Formatting data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 93
diff changeset
   545
				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
   546
				<ul>
91
3ed9f08a1f23 Renames for readability
Takeshi Yoshino <tyoshino@google.com>
parents: 90
diff changeset
   547
					<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
   548
					<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
   549
					<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
   550
				</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   551
			</p>
94
e06bf08768db Formatting data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 93
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
			<p>
94
e06bf08768db Formatting data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents: 93
diff changeset
   554
				A WritableByteStream 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
   555
				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
   556
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   557
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
				To <dfn>process pendingWriteQueue</dfn>, repeat the steps below:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   560
				<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   561
					<li>If <a>pendingWriteQueue</a> is empty, break from this loop</li>
91
3ed9f08a1f23 Renames for readability
Takeshi Yoshino <tyoshino@google.com>
parents: 90
diff changeset
   562
					<li>Let <var>pendingWrite</var> be the head element of <a>pendingWriteQueue</a></li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   563
					<li>Let <var>amountToAcknowledge</var> be min(<var>pendingWrite.amount</var> - <var>pendingWrite.ackedAmount</var>, <a>spaceAvailable</a>)</li>
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   564
					<li>Set <a>spaceAvailable</a> to <a>spaceAvailable</a> - <var>amountToAcknowledge</var></li>
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   565
					<li>Set <var>pendingWrite.ackedAmount</var> to <var>pendingWrite.ackedAmount</var> + <var>amountToAcknowledge</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   566
					<li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   567
						If <var>pendingWrite.ackedAmount</var> equals to <var>pendingWrite.amount</var>, 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
   568
						<ol>
91
3ed9f08a1f23 Renames for readability
Takeshi Yoshino <tyoshino@google.com>
parents: 90
diff changeset
   569
							<li>Pop <var>pendingWrite</var> from <a>pendingWriteQueue</a></li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   570
							<li>If <var>pendingWrite.promise</var> is not <code>null</code>, fulfill it with <var>pendingWrite.amount</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   571
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   572
				</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   573
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   574
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   575
			<p>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   576
				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
   577
				<ol>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   578
					<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
   579
					<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
   580
				</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   581
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   582
		</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   583
	</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   584
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   585
	<section class="section" id="readableByteStream">
89
9ff7e872e1e8 Type Steam -> Stream
Takeshi Yoshino <tyoshino@google.com>
parents: 88
diff changeset
   586
		<h2>ReadableByteStream Interface</h2>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   587
		<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   588
			The ReadableByteStream interface defines a protocol for APIs which produce a byte stream. This protocol includes:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   589
			<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   590
				<li>How to receive a read request from the reader and output bytes</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   591
				<li>How to transfer data in bulk to another <a>WritableByteStream</a> (by using the <code>pipe()</code> method)</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   592
				<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
   593
			</ol>
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
			By returning a <a>Promise</a> and delaying fulfillment of it, the ReadableByteStream realizes asynchronous data consumption.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   596
		</p>
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>
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   599
			Interfaces introduced in this section provide simple and convenient ways to consume data.
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   600
			They connect arbitrary byte stream producer and byte stream consuming JavaScript code using Promises and method invocations.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   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>
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   604
			A ReadableByteStream 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>.
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
   605
			A data source, however, can have a one-to-many relationship with ReadableByteStream, 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
   606
		</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   607
77
3e2335dbad62 Rewording
Takeshi Yoshino <tyoshino@google.com>
parents: 76
diff changeset
   608
		<section class="section" id="readableByteStreamInterface">
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   609
			<h3>ReadableByteStream interface</h3>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   610
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   611
			<dl class="idl" title="interface ReadableByteStream">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   612
				<dt>readonly attribute DOMString type</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   613
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   614
					Returns the ASCII-encoded string in lower case representing the media type of the <code>Stream</code>,
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   615
					expressed as an RFC2046 MIME type [[!RFC2046]].
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   616
					Conforming user agents SHOULD return the MIME type of the <code>ReadableByteStream</code>, if it is known.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   617
					If conforming user agents cannot determine the media type of the <code>ReadableByteStream</code>, they MUST return the empty string.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   618
					A string is a valid MIME type if it matches the media-type token defined in section 3.7 "Media Types" of RFC 2616 [[!HTTP11]].
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   619
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   620
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   621
				<dt>attribute ByteStreamReadType readType</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   622
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   623
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   624
						Specifies what data type will be returned by a <code>read()</code> and <code>readExact()</code> method call.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   625
						This attribute can be set to any of the supported types in <a>ByteStreamReadType</a>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   626
						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
   627
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   628
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   629
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   630
				<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
   631
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   632
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   633
						Specifies a <a>DOMString</a> that represents the label of an encoding [[!EncodingDetermination]].
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   634
						If set, it will be used as part of the encoding determination used when processing a <code>read()</code> method call.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   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
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   638
						This parameter is not designed to be specified as an argument of <code>read()</code> since it's not likely to be changed frequently.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   639
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   640
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   641
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   642
				<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
   643
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   644
					<p>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   645
						This attribute provides ReadableByteStream with a hint of how much data the reader can consume currently.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   646
						Each implementation of ReadableByteStream must initialize the value of pullAmount on construction.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   647
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   648
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   649
					<p>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   650
						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
   651
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   652
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   653
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   654
						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
   655
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   656
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   657
						It's possible that the number of bytes received by <code>read()</code> is more than the pullAmount value.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   658
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   659
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   660
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   661
				<dt>Promise&amp;lt;ByteStreamReadResult&gt; readExact()</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   662
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   663
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   664
						This method reads data from the ReadableByteStream.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   665
						The returned Promise is fulfilled only when bytes of the specified size is read or the EOF is reached.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   666
						The size of data read by this method is exactly the same as the specified size unless an EOF was reached, in which case there will be less bytes, which were the remaining bytes until the EOF.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   667
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   668
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   669
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   670
						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
   671
						<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   672
							<li>If <a href="#widl-ReadableByteStream-readType">readType</a> is "<code>text</code>" throw a "<code><a>SyntaxError</a></code>"</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   673
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   674
							<li>If <a>readPending</a> is set, throw an "<code><a>InvalidStateError</a></code>"</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   675
							<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
   676
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   677
							<li>Let <var>latchedType</var> be the current value of <a href="#widl-ReadableByteStream-readType">readType</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   678
							<li>Let <var>latchedEncoding</var> be the current value of <a href="#widl-ReadableByteStream-readEncoding">readEncoding</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   679
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   680
							<li>Set <a>readExactPullAmount</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
   681
							<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
   682
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   683
							<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
   684
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   685
							<li>Let <var>readPromise</var> be a new <a>Promise</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   686
							<li>Return <var>readPromise</var>, and then continue to process the steps in this algorithm</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   687
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   688
							<li>Wait until the number of bytes in <a>readDataBuffer</a> becomes equal to or greater than <var>size</var> or <a>eofReached</a> is set</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   689
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   690
							<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   691
								Queue a task which runs the steps below:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   692
								<ol>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   693
									<li>Let <var>readableAmount</var> be the number of bytes in <a>readDataBuffer</a></li>
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   694
									<li>Let <var>amountToReturn</var> be min(<var>size</var>, <var>readableAmount</var>)</li>
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   695
									<li>Set <a>amountBeingReturned</a> to <var>amountToReturn</var></li>
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   696
									<li>Pop <var>amountToReturn</var> bytes from <a>readDataBuffer</a>, and then let <var>readBytes</var> be the popped bytes</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   697
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   698
									<li>Set <a>readExactPullAmount</a> to 0</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   699
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   700
									<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
   701
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   702
									<li>Let <var>result</var> be a new <a>ByteStreamReadResult</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   703
									<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   704
										<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   705
											<dt>If <var>latchedType</var> is "<code>none</code>"</dt>
108
2cd69f4494a8 More "foo of bar" -> "bar.foo"
Takeshi Yoshino <tyoshino@google.com>
parents: 107
diff changeset
   706
											<dd>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-data">data</a> to <code>undefined</code></dd>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   707
											<dt>Otherwise</dt>
108
2cd69f4494a8 More "foo of bar" -> "bar.foo"
Takeshi Yoshino <tyoshino@google.com>
parents: 107
diff changeset
   708
											<dd>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-data">data</a> to an object of the type specified by <var>latchedType</var> which represents <var>readBytes</var></dd>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   709
										</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   710
									</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   711
									<li>Set <a href="#widl-ByteStreamReadResult-eof">eof</a> of <var>result</var> to <code>true</code> if <a>readDataBuffer</a> is empty and <a>eofReached</a> is set</li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   712
									<li>Set <a href="#widl-ByteStreamReadResult-amountConsumed">amountConsumed</a> of <var>result</var> to <var>amountToReturn</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   713
									<li>Fulfill <var>readPromise</var> with <var>result</var></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   714
								</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   715
							</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   716
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   717
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   718
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   719
					<dl class="parameters">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   720
						<dt>[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
   721
						<dd>Number of bytes to read.</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   722
					</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   723
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   724
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   725
						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
   726
						<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   727
							<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
   728
							<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
   729
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   730
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   731
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   732
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   733
				<dt>Promise&amp;lt;ByteStreamReadResult&gt; read()</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   734
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   735
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   736
						This method reads data from the ReadableByteStream.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   737
						The speed of reading can be roughly adjusted by using <a href="#widl-ByteStreamReadResult-pullAmount">pullAmount</a>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   738
						pullAmount doesn't necessarily limit the size of data being read by this method.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   739
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   740
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   741
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   742
						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
   743
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   744
						<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   745
							<li>If <a>readPending</a> is set, throw an "<code><a>InvalidStateError</a></code>"</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   746
							<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
   747
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   748
							<li>Let <var>latchedType</var> be the current value of <a href="#widl-ReadableByteStream-readType">readType</a> attribute</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   749
							<li>Let <var>latchedEncoding</var> be the current value of <a href="#widl-ReadableByteStream-readEncoding">readEncoding</a> attribute</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   750
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   751
							<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
   752
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   753
							<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
   754
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   755
							<li>Let <var>readPromise</var> be a new <a>Promise</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   756
							<li>Return <var>readPromise</var>, and then continue to process the steps in this algorithm</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   757
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   758
							<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   759
								<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   760
									<dt>If <var>latchedType</var> is "<code>text</code>"</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   761
									<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   762
										<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   763
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   764
												Wait until bytes in <a>readDataBuffer</a> can be converted into a non-empty <a>DOMString</a> when decoded using <var>latchedEncoding</var> 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
   765
											</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   766
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   767
												Queue a task which runs the rest of this algorithm
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   768
											</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   769
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   770
												Pop non-zero number of bytes from <a>readDataBuffer</a> which can be fully converted into a non-empty <a>DOMString</a> when decoded using <var>latchedEncoding</var>, and then let <var>readBytes</var> be the result of the conversion.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   771
												If <a>eofReached</a> is set and there are no such bytes, reject <var>readPromise</var> and terminate these steps.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   772
											</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   773
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   774
												Let <var>readData</var> be the result of decoding <var>readBytes</var> using <var>latchedEncoding</var>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   775
												If this throws an <var>exception</var>, reject <var>readPromise</var> with <var>exception</var>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   776
											</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   777
										</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   778
									</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   779
									<dt>Otherwise</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   780
									<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   781
										<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   782
											<li>Wait until <a>readDataBuffer</a> becomes non-empty or <a>eofReached</a> is set</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   783
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   784
												Queue a task which runs the rest of this algorithm
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   785
											</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   786
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   787
												Pop non-zero number of bytes from <a>readDataBuffer</a>, and then let <var>readBytes</var> be the popped bytes
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   788
												<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   789
													Implementations may choose to pop only part of bytes readable if it helps reducing memory copy.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   790
												</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   791
											</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   792
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   793
												<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   794
													<dt>If <var>latchedType</var> is "<code>none</code>"</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   795
													<dd>Let <var>readData</var> be <code>undefined</code></dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   796
													<dt>Otherwise</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   797
													<dd>Let <var>readData</var> be an object of the type specified by <var>latchedType</var> which represents <var>readBytes</var></dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   798
												</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   799
											</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   800
										</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   801
									</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   802
								</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   803
							</li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   804
							<li>Let <var>amountConsumed</var> be the size of <var>readBytes</var></li>
76
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
							<li>Let <var>result</var> be a new <a>ByteStreamReadResult</a>.</li>
106
4b349a87fc7c More foo of bar -> bar.foo clean up
Takeshi Yoshino <tyoshino@google.com>
parents: 105
diff changeset
   807
							<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-data">data</a> to <var>readData</var></li>
4b349a87fc7c More foo of bar -> bar.foo clean up
Takeshi Yoshino <tyoshino@google.com>
parents: 105
diff changeset
   808
							<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-eof">eof</a> to <code>true</code> if <a>eofReached</a> is set and <a>readDataBuffer</a> is empty</li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   809
							<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-amountConsumed">amountConsumed</a> to <var>amountConsumed</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   810
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   811
							<li>Set <a>amountBeingReturned</a> to <var>amountConsumed</var></li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   812
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   813
							<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
   814
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   815
							<li>Fulfill <var>readPromise</var> with <var>result</var></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   816
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   817
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   818
78
12c164bee09f Add diagrams
Takeshi Yoshino <tyoshino@google.com>
parents: 77
diff changeset
   819
					<p>
83
afed6501a898 moved images, fixed typos, fixed header
fmoussa <feras.moussa@hotmail.com>
parents: 81
diff changeset
   820
						<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
   821
					</p>
12c164bee09f Add diagrams
Takeshi Yoshino <tyoshino@google.com>
parents: 77
diff changeset
   822
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   823
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   824
						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
   825
						<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   826
							<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
   827
							<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
   828
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   829
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   830
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   831
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   832
				<dt>Promise&amp;lt;ByteStreamReadResult&gt; pipe()</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   833
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   834
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   835
						This method bulk transfers bytes from the ReadableByteStream to another <a>WritableByteStream</a>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   836
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   837
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   838
					<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   839
						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
   840
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   841
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   842
					<section class="note">
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   843
						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
   844
					</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   845
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   846
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   847
						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
   848
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   849
						<ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   850
							<li>If <a>readPending</a> is set, throw an "<code><a>InvalidStateError</a></code>"</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   851
							<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
   852
110
6a7a40bde1e5 Abort wait -> abort waiting
Takeshi Yoshino <tyoshino@google.com>
parents: 109
diff changeset
   853
							<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
   854
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   855
							<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
   856
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   857
							<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
   858
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   859
							<li>Let <var>pipePromise</var> be a new <a>Promise</a></li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   860
							<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
   861
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   862
							<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
   863
							<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   864
								Repeat the steps below:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   865
								<ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   866
									<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   867
										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
   868
										<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   869
											<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
   870
											<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
   871
											<dt>Otherwise</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   872
											<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
   873
										</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   874
										<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
   875
											<li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   876
												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
   877
												<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
   878
													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
   879
												</section>
7421b9a22a7e More bug fix in pipe(). numBytesRequested is used where numBytesSpaceAvailable must be used.
Takeshi Yoshino <tyoshino@google.com>
parents: 99
diff changeset
   880
											</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   881
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   882
												<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   883
													<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
   884
													<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
   885
													<dt>Otherwise</dt>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   886
													<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
   887
												</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   888
											</li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   889
											<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
   890
											<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
   891
98
3b89f8cea0fd More tuple -> pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents: 97
diff changeset
   892
											<li>Let <var>pendingWrite</var> be a new <a>PendingWriteDescriptor</a></li>
3b89f8cea0fd More tuple -> pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents: 97
diff changeset
   893
											<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
   894
											<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
   895
											<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
   896
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   897
											<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
   898
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   899
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   900
												<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   901
													<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
   902
													<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
   903
													<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
   904
													<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
   905
												</dl>
102
a176607d4c3a TODO about pipe() finish timing
Takeshi Yoshino <tyoshino@google.com>
parents: 101
diff changeset
   906
												<section class="note">
a176607d4c3a TODO about pipe() finish timing
Takeshi Yoshino <tyoshino@google.com>
parents: 101
diff changeset
   907
													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
   908
												</section>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   909
											</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   910
										</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   911
									</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   912
									<li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   913
										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
   914
										<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   915
											<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
   916
											<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
   917
											<dt>Otherwise</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   918
											<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
   919
										</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   920
										<ol>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   921
											<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
   922
											<li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   923
												<dl class="switch">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   924
													<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
   925
													<dd>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   926
														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
   927
														<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   928
															If <a href="#widl-ReadableByteStream-pullAmount">pullAmount</a> is set to 0, pipe() transfers data in pull style.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   929
															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
   930
														</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   931
														<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   932
															Setting <a href="#widl-ReadableByteStream-pullAmount">pullAmount</a> to a small value doesn't have an effect of throttling the pace of pipe().
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   933
														</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   934
													</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   935
													<dt>Otherwise</dt>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   936
													<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
   937
												</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   938
											</li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   939
											<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
   940
											<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
   941
										</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   942
									</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   943
								</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   944
							</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   945
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   946
							<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
   947
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   948
							<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
   949
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   950
							<li>Let <var>result</var> be a new <a>ByteStreamReadResult</a></li>
105
0ba39ba3955b Fix typo in pipe() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents: 104
diff changeset
   951
							<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-data">data</a> to <code>undefined</code>.
101
7da4a886ff9f More pipe() bug fixes
Takeshi Yoshino <tyoshino@google.com>
parents: 100
diff changeset
   952
							<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-eof">eof</a> to <code>true</code> if <a>eofReached</a></li>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   953
							<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-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
   954
							<li>
101
7da4a886ff9f More pipe() bug fixes
Takeshi Yoshino <tyoshino@google.com>
parents: 100
diff changeset
   955
								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
   956
								<section class="note">
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   957
									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
   958
								</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   959
							</li>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   960
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   961
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   962
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   963
					<dl class="parameters">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   964
						<dt>WritableByteStream destination</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   965
						<dd>Destination <a>WritableByteStream</a>.</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   966
						<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
   967
						<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
   968
					</dl>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   969
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   970
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   971
				<dt>ReadableByteStream fork()</dt>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   972
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   973
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   974
						This method creates a new ReadableByteStream which refers to the same <a>dataSource</a> as the current ReadableByteStream.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   975
						Data sources are range reference counted so that a range in a data source is freed only when all the ReadableByteStreams sharing the data source finish consuming it.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   976
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   977
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   978
					<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   979
						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
   980
						<ol>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   981
							<li>Let <var>branch</var> be a new ReadableByteStream 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 ReadableByteStream.</li>
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
   982
							<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
   983
							<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
   984
						</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   985
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   986
				</dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   987
104
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
   988
				<dt>Promise&amp;lt;undefined&gt; readClose()</dt>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   989
				<dd>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
   990
					<p>
104
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
   991
						This method tells the ReadableByteStream that no more data will be read from it without indication of any error.
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
   992
					</p>
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
   993
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
   994
					<p>
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
   995
						This method must run the steps below:
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
   996
						<ol>
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
   997
							<li>Let <var>closePromise</var> be a new <a>Promise</a></li>
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
   998
							<li>Return <var>closePromise</var>, and then continue the process the steps in this algorithm</li>
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
   999
							<li>Notify <a>dataSource</a> of readClosure</li>
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
  1000
							<li>Wait until <a>dataSource</a> acknowledges the readClosure</li>
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
  1001
							<li>Fulfill <var>closePromise</var> with <code>undefined</code></li>
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
  1002
						</ol>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1003
					</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1004
				</dd>
37
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
  1005
			</dl>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
  1006
		</section>
0de575d7b79a - Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents: 35
diff changeset
  1007
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1008
		<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
  1009
			<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
  1010
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1011
			<p>
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1012
				A data source produces the bytes to be consumed via the <a>ReadableByteStream</a> interface instances.
95
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1013
				A <a>ReadableByteStream</a> retrieves bytes from an associated data source.
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1014
				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-ReadableByteStream-fork-ReadableByteStream">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
  1015
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1016
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1017
			<p>
95
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1018
				A <dfn>data source</dfn> can be anything that:
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1019
				<ul>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1020
					<li>
95
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1021
						Produces bytes. Newly produced bytes will be delivered to the associated <a>ReadableByteStream</a>.
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1022
					</li>
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1023
					<li>
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1024
						Accepts requests for production of bytes from a <a>ReadableByteStream</a>. 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
  1025
						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
  1026
						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
  1027
						Requests and delivery of bytes don't need to 1-to-1 correspond.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1028
						Data sources may produce bytes and send to <a>ReadableByteStream</a> unsolicitedly without receiving any retrieval request.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1029
					</li>
104
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
  1030
					<li>
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
  1031
						Accepts and acknowledges readClosure signal which means the associated <a>ReadableByteStream</a> has completed consuming bytes from this data source without indication of any error.
69234a5f02a6 Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents: 103
diff changeset
  1032
					</li>
95
af7f31ca4da3 Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents: 94
diff changeset
  1033
				</ul>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1034
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1035
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1036
			<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1037
				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
  1038
				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
  1039
				<ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1040
					<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
  1041
					<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
  1042
					<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
  1043
					<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
  1044
					<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
  1045
				</ul>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1046
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1047
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1048
			<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1049
				When <a href="#widl-ReadableByteStream-fork-ReadableByteStream">fork()</a> is called, a new reader is registered to the original <a>ReadableByteStream</a>'s data source and the new <a>ReadableByteStream</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
  1050
			</p>
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1051
		</section>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1052
87
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1053
		<section class="section" id="interactingWithDataSource">
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1054
			<h2>Interacting with the data source</h2>
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1055
dcf26e7c77fe Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents: 86
diff changeset
  1056
			<section class="note">
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1057
				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
  1058
				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
  1059
			</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1060
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1061
			<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1062
				A ReadableByteStream has an associated <a>data source</a> referred by <dfn>dataSource</dfn> from which the ReadableByteStream retrieves bytes.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1063
				The data source model is explained in <a href="#h2_data_source">this section</a>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1064
				A data source can be shared by multiple ReadableByteStream instances when <code>fork()</code> is used.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1065
				A ReadableByteStream is registered with a data source on construction and given a reader ID.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1066
				The <a>dataSource</a> of a ReadableByteStream refers to its data source, and <dfn>readerId</dfn> of a ReadableByteStream refers to its reader ID.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1067
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1068
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1069
			<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1070
				A ReadableByteStream has the following internal mechanisms:
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1071
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1072
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1073
			<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1074
				An associated flag <dfn>readPending</dfn> which prevents multiple read operations from being run.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1075
				This flag is set to false on construction.
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>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1079
				An associated integer variable <dfn>readExactPullAmount</dfn> which temporarily overrides <a href="#widl-ReadableByteStream-pullAmount">pullAmount</a> if necessary for a <code>readExact()</code> method call.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1080
				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
  1081
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1082
			<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1083
				An associated integer variable <dfn>pipePullAmount</dfn> which temporarily overrides <a href="#widl-ReadableByteStream-pullAmount">pullAmount</a> if necessary for a <code>pipe()</code> method call.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1084
				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
  1085
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1086
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1087
			<p>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1088
				An associated integer variable <dfn>amountRequested</dfn> which holds the number of bytes being retrieved from the <a>dataSource</a>.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1089
				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
  1090
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1091
			<p>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1092
				An associated integer variable <dfn>amountBeingReturned</dfn> which holds the number of bytes consumed on the last read operation.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1093
				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
  1094
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1095
				<section class="note">
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1096
					amountBeingReturned delays replenishment of pullAmount until the next read()/pipe() operation is made.
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1097
				</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1098
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1099
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1100
			<p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1101
				An associated queue <dfn>readDataBuffer</dfn> which holds the bytes retrieved from <a>dataSource</a>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1102
				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
  1103
				<section class="note">
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1104
					Retrieved bytes can be queued in <a>readDataBuffer</a> in any form.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1105
					For example, if bytes were retrieved as <a>ArrayBufferView</a> fragments, it's ok to store them as-is to avoid unnecessary copy.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1106
					If the object representing retrieved bytes is a DOMString, that should be accompanied with the encoding to use to decode it.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1107
				</section>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1108
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1109
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1110
			<p>
83
afed6501a898 moved images, fixed typos, fixed header
fmoussa <feras.moussa@hotmail.com>
parents: 81
diff changeset
  1111
				<img src="images/readdatabuffer.png" alt="Read data buffer related variables">
78
12c164bee09f Add diagrams
Takeshi Yoshino <tyoshino@google.com>
parents: 77
diff changeset
  1112
			</p>
12c164bee09f Add diagrams
Takeshi Yoshino <tyoshino@google.com>
parents: 77
diff changeset
  1113
12c164bee09f Add diagrams
Takeshi Yoshino <tyoshino@google.com>
parents: 77
diff changeset
  1114
			<p>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1115
				An associated flag <dfn>eofReached</dfn> which indicates that the EOF was received from the <a>dataSource</a>.
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1116
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1117
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1118
			<p>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1119
				To <dfn>retrieve data</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
  1120
				<ol>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1121
					<li>Let <var>readableAmount</var> be the number of bytes in the <a>readDataBuffer</a></li>
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1122
					<li>Let <var>amountToRetrieve</var> be max(max(<a href="#widl-ReadableByteStream-pullAmount">pullAmount</a>, <a>readExactPullAmount</a>, <a>pipePullAmount</a>) - (<a>amountRequested</a> + <var>readableAmount</var> + <a>amountBeingReturned</a>), 0)</li>
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1123
					<li>Set <a>amountRequested</a> to <a>amountRequested</a> + <var>amountToRetrieve</var></li>
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1124
					<li>Send a request to the <a>dataSource</a> to return <var>amountToRetrieve</var> bytes to the ReadableByteStream</li>
76
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1125
				</ol>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1126
			</p>
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1127
63f6521d7457 Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents: 46
diff changeset
  1128
			<p>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1129
				When data is received from <a>dataSource</a>, 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
  1130
				<ol>
107
276491848949 Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents: 106
diff changeset
  1131
					<li>Let <var>receivedData</var> be the received bytes</li>
276491848949 Rename variables agnostic to type of data Streams API handles
Take&