author  Takeshi Yoshino <tyoshino@google.com> 
Tue, 28 Jan 2014 14:56:24 +0900  
changeset 137  142342673c3f 
parent 136  351c58f63ce5 
child 138  6cc871794be1 
permissions  rwrr 
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=utf8" httpequiv="ContentType"> 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.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/respecw3ccommon"></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="respecw3ccommon.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/shortname/ 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

19 
shortName: "streamsapi", 
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: "yyyymmdd", 
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 YYYYMMDD 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: "yyyymmdd", 
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/streamsapi/rawfile/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: "20090805", 
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/W3CED.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: "publicwebapps", 
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 Rectrack 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 Rectrack 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@ELIOTGRAX220.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 { bordercollapse:collapse; borderstyle: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 { borderbottom: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:firstchild { borderleft: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 { borderleft:solid; borderright:solid; borderbottom:solid thin; verticalalign: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  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/streamsapi/">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  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@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

121 
<p> 
124
9dc273a030cc
 ByteStreamReadResult > StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents:
123
diff
changeset

122 
This specification provides an API for representing a stream of data in web applications, as well as programmatically reading and writing it. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

123 
This includes: 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

124 
</p> 
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

125 
<ul> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

126 
<li> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

127 
An interface named <a>WritableStream</a> which defines a general protocol for data consuming APIs (<a href="#consumers">consumers</a>) to communicate with data producing code (<a href="#producers">producers</a>). 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

128 
</li> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

129 
<li> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

130 
An interface named <a>ReadableStream</a> which defines a general protocol for data producing APIs to communicate with data consuming code. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

131 
</li> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

132 
<li> 
124
9dc273a030cc
 ByteStreamReadResult > StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents:
123
diff
changeset

133 
An interface named <a>ByteStream</a> which inherits both WritableStream and ReadableStream and represents a sequence of data. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

134 
</li> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

135 
<li> 
124
9dc273a030cc
 ByteStreamReadResult > StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents:
123
diff
changeset

136 
A struct type named <a>StreamReadResult</a> which represents the result of consuming operations such as <code>read()</code> and <code>pipe()</code>. 
125
98448480356b
ByteStreamReadType > StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents:
124
diff
changeset

137 
It holds: 
98448480356b
ByteStreamReadType > StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents:
124
diff
changeset

138 
<ul> 
98448480356b
ByteStreamReadType > StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents:
124
diff
changeset

139 
<li>Chunk of content read from a <a>ReadableStream</a></li> 
98448480356b
ByteStreamReadType > StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents:
124
diff
changeset

140 
<li>The total cost of the chunk</li> 
98448480356b
ByteStreamReadType > StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents:
124
diff
changeset

141 
<li>EOF signal</li> 
98448480356b
ByteStreamReadType > StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents:
124
diff
changeset

142 
<li>Error info</li> 
98448480356b
ByteStreamReadType > StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents:
124
diff
changeset

143 
</ul> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

144 
</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

145 
<li> 
125
98448480356b
ByteStreamReadType > StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents:
124
diff
changeset

146 
An enum <a>StreamReadType</a> which represents data types as which data can be read from a <a>ReadableStream</a>. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

147 
</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

148 
<li> 
126  149 
A list of notable data <a href="#producers">producers</a> and <a href="#consumers">consumers</a> for which we can apply either or both of <a>ReadableStream</a> and <a>WritableStream</a> model. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

150 
</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

151 
<li> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

152 
Extensions to <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest2/#thexmlhttprequestinterface">XMLHttpRequest</a> [[!XMLHTTPREQUEST2]] to add support for uploading data via <a>WritableStream</a> and downloading a response as a <a>ReadableStream</a>. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

153 
</li> 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

154 
<li> 
126  155 
Extensions to <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfncreateObjectURL">URL.createObjectURL</a> and <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfnrevokeObjectURL">URL.revokeObjectURL</a> to add support for <a>ReadableStream</a>. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

156 
</li> 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

157 
</ul> 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

158 

0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

159 
<p> 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

160 
This API is designed to be used in conjunction with other APIs and elements on the web platform, notably: 
126  161 
<ul> 
162 
<li><a href="http://dev.w3.org/2006/webapi/FileAPI">FileAPI</a> [[!FILEAPI]]</li> 

163 
<li> 

164 
<a href="http://dev.w3.org/2006/webapi/XMLHttpRequest2">XMLHttpRequest</a>. 

165 
E.g. with an overloaded <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest2/#thesendmethod"><code>send()</code></a> method and <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest2/#theresponsetypeattribute"><code>response</code></a> object for <a>ReadableStream</a> objects) [[!XMLHTTPREQUEST2]]. 

166 
</li> 

167 
<li><a href="http://dev.w3.org/html5/postmsg/#domwindowpostmessage"><code>postMessage</code></a></li> 

168 
<li>Web Workers [[!WEBWORKERS]]</li> 

169 
</ul> 

0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

170 
</p> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

171 
</section> 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

172 

37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

173 
<section id="introduction" class="section informative"> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

174 
<h2>Introduction</h2> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

175 

0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

176 
<p> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

177 
Web applications should have the ability to acquire, manipulate, and pass data in a wide variety of forms, including as a sequence of data made available over time. 
126  178 
This specification defines the basic representation for streams of data, and programmatic ways to read and write streams of data and errors raised on those operations. 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

179 
</p> 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

180 

01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

181 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

182 
The <a>WritableStream</a> interface defines a general protocol for <a href="#consumers">data consuming APIs</a> to communicate with data producing code. 
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

183 
In these cases, the data consuming API, such as a decoder, provides a <a>WritableStream</a> for other applications to write to, enabling the decoder to begin decoding data as it becomes available. 
126  184 
The data is written to the internal data sink inside the data consuming API using: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

185 
<ul> 
87
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

186 
<li> 
126  187 
The <code>write()</code> method which writes the given data to the data sink 
188 
</li> 

189 
<li> 

190 
The <code>awaitSpaceAvailable()</code> method which allows a data producing code to write data to the data consuming API only when its data sink is available to consume more data. 

191 
This is useful for cases where an app may want to avoid filling the internal buffer. 

87
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

192 
</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

193 
</ul> 
126  194 
Actual transfer of data to the data sink may happen either synchronously or asynchronously. 
195 
<a>WritableStream</a> hides the details of actual communication with the data sink while allowing for an efficient transfer of data. 

24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

196 
</p> 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

197 

01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

198 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

199 
The <a>ReadableStream</a> interface defines a general protocol for <a href="#producers">data producing APIs</a> to communicate with data consuming code. 
126  200 
This interface represents the potential for an infinite amount of data which are obtained over time and read once. 
201 
Data consuming code reads data from the internal data source inside the data producing API using: 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

202 
<ul> 
126  203 
<li> 
204 
The <code>read()</code> and <code>readUpTo()</code> methods which reads data from the data source 

205 
</li> 

206 
<li> 

207 
The <code>pullAmount</code> attribute which paces data retrieval from the data source 

208 
</li> 

209 
<li> 

210 
The <code>pipe()</code> method which transfers data in bulk from the data source into the data sink of another API which implements <a>WritableStream</a> 

211 
</li> 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

212 
</ul> 
126  213 
Actual transfer of data from the data source may happen either synchronously or asynchronously. 
214 
The <a>ReadableStream</a> hides the details of actual communication with the data source while allowing for an efficient transfer of data. 

24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

215 
</p> 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

216 

01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

217 
<p> 
126  218 
With the combination of the following features, this interface suite responds to various simple and complex needs of data stream handling. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

219 
<ul> 
126  220 
<li>Delayed notification of completion by using <a>Promise</a>s. See below for more details.</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

221 
<li>Explicit back pressure management by propagating room for consumption back to producers</li> 
126  222 
<li><a>WritableStream</a> always accepts incoming data synchronously to bridge with legacy APIs that don't understand backpressure</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

223 
</ul> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

224 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

225 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

226 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

227 
The <a>ByteStream</a> is a simple implementation of both the <a>WritableStream</a> and <a>ReadableStream</a> interface. 
126  228 
A ByteStream has a single queue of bytes which works as a data sink for the WritableStream interface and as a data source for the ReadableStream interface. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

229 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

230 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

231 
<p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

232 
Read and write operations on these interfaces are implemented using <a>Promise</a>. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

233 
When an operation completes, the Promise returned by a method will be fulfilled, and then the fulfill callback set to the Promise will handle the result. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

234 
Error conditions that may arise during an operation will be handled by the reject callback set to the Promise. 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

235 
</p> 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

236 

37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

237 
<p> 
131
5db012bd990c
Make URI stuff more separate
Takeshi Yoshino <tyoshino@google.com>
parents:
130
diff
changeset

238 
The base stream classes are defined as JavaScript primitives. 
5db012bd990c
Make URI stuff more separate
Takeshi Yoshino <tyoshino@google.com>
parents:
130
diff
changeset

239 
Extensions to it for use in browsers are defined separately. 
5db012bd990c
Make URI stuff more separate
Takeshi Yoshino <tyoshino@google.com>
parents:
130
diff
changeset

240 
</p> 
5db012bd990c
Make URI stuff more separate
Takeshi Yoshino <tyoshino@google.com>
parents:
130
diff
changeset

241 

5db012bd990c
Make URI stuff more separate
Takeshi Yoshino <tyoshino@google.com>
parents:
130
diff
changeset

242 
<p> 
126  243 
Examples below will be illustrative. 
244 
</p> 

245 

246 
<p> 

247 
The example below demonstrates how to read a chunk of data from a <a>ReadableStream</a> using <code>read()</code>. 

123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

248 
The <a>ReadableStream</a> may of come from a <a href="#producers">producer</a> such as <code>XMLHttpRequest</code>. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

249 
</p> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

250 

77  251 
<pre class="example"> 
252 
// Tell stream that we're ready to consume 1024 bytes. 

253 
stream.pullAmount = 1024; 

24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

254 
stream.readEncoding = "UTF8"; 
121  255 
stream.readBinaryAs = "arraybuffer"; 
77  256 
stream.read().then( 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

257 
function (result) { 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

258 
// Process data 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

259 
}, 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

260 
function (error) { 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

261 
// Handle error 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

262 
});</pre> 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

263 

126  264 
<p> 
265 
The example below demonstrates how to read bytes from a <a>ReadableStream</a> until an EOF is encountered. 

266 
</p> 

267 

123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

268 
<pre class="example">// Read data from the ReadableStream repeatedly 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

269 
function readUntilEof() { 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

270 
stream.read().then( 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

271 
function (result) { 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

272 
processData(result.data); 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

273 

24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

274 
if (!result.eof) { 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

275 
readUntilEof(); 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

276 
} 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

277 
}, 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

278 
function (error) { 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

279 
// Handle error 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

280 
}); 
8
cb4e62ad9587
Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents:
7
diff
changeset

281 
} 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

282 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

283 
readUntilEof();</pre> 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

284 

37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

285 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

286 
The example below demonstrates how to obtain a <a>ReadableStream</a> from <a>XMLHttpRequest</a> to begin playing a large video in <code>readystate</code> LOADING. 
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

287 
The example takes the <a>ReadableStream</a> from a <a href="#producers">producer</a>, <a>XMLHttpRequest</a>, and gives it to a <a href="#consumers">consumer</a>, the video tag. 
126  288 
If the consumer implements the <a>WritableStream</a> interface, we could use <code>pipe()</code> to transfer data to it instead of URL. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

289 
</p> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

290 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

291 
<pre class="example">function handler() { 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

292 
if(this.readyState == this.LOADING) { 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

293 
var theStream = this.response; 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

294 
var streamURL = URL.createObjectURL(theStream); 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

295 
document.getElementById("myVideoTag").src = streamURL; 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

296 
} 
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

297 
} 
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

298 

af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

299 
var client = new XMLHttpRequest(); 
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

300 
client.onreadystatechange = handler; 
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

301 
client.setRequestHeader('customHeader', 'value'); 
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

302 
client.setRequestHeader('customHeader2', 'value2'); 
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

303 
client.open("GET", "myvideo.h264"); 
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

304 
client.responseType = "stream"; 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

305 
client.send();</pre> 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

306 

0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

307 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

308 
The example below demonstrates how to use <code>write()</code> to load a <a>ReadableStream</a> into the audio tag, whose data could be processed and built dynamically at read time. 
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

309 
ByteStream in the example is a class which implements both <a>WritableStream</a> and <a>ReadableStream</a>. 
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

310 
It accepts bytes generated by the code via <a>WritableStream</a> methods, and the written data will be consumed by the audio element via the object URL which is a part of <a>ReadableStream</a>'s functionality. 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

311 
</p> 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

312 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

313 
<pre class="example">var stream = new ByteStream("audio/mp3"); 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

314 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

315 
function writeData() { 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

316 
// Do work to create more data to place into the stream 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

317 
var data = generateMusic(); 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

318 

01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

319 
// If we have no more data to process and place in the stream, we close 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

320 
if (moreData == null){ 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

321 
stream.writeClose(); 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

322 
} else{ 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

323 
// Wait until write() completes. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

324 
stream.write(data).then( 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

325 
function () { 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

326 
writeData(); 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

327 
}, 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

328 
function (error) { 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

329 
// Handle error 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

330 
} 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

331 
); 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

332 
} 
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

333 
} 
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

334 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

335 
var streamURL = URL.createObjectURL(stream); 
8
cb4e62ad9587
Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents:
7
diff
changeset

336 
document.getElementById('audioTag').src = streamURL; 
cb4e62ad9587
Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents:
7
diff
changeset

337 

24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

338 
writeData();</pre> 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

339 

01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

340 
<p> 
126  341 
A producer can also do work only when pulled by using <code>awaitSpaceAvailable()</code>. 
342 
This method informs the data producing code of that the data consuming API is ready to consume data. 

87
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

343 
This is useful when highperformance is necessary. 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

344 
</p> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

345 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

346 
<pre class="example">function poll() { 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

347 
stream.awaitSpaceAvailable().then( 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

348 
function (pulledAmount) { 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

349 
stream.write(generateRandomBytes(pulledAmount)); 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

350 
poll(); 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

351 
} 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

352 
); 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

353 
} 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

354 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

355 
poll();</pre> 
113
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

356 

b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

357 
<p> 
126  358 
The example below demonstrates how the timing to pull new data is determined. 
359 
When data of cost X is loaded and passed to the Promise, the <a>ReadableStream</a> marks X bytes of pullAmount as used. 

360 
The next <code>read()</code> call automatically clears the mask to request the data source to produce X more data. 

113
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

361 
If precise flow control is needed, you update pullAmount before the next <code>read()</code>. 
126  362 
In the example, the producer API is requested to produce 16 bytes, and then in the fulfill callback, pullAmount is set to the remaining number of bytes not to let the API produce more data. 
113
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

363 
</p> 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

364 

b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

365 
<pre class="example">stream.pullAmount = 16; 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

366 
function read() { 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

367 
stream.read().then( 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

368 
function (result) { 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

369 
process(result); 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

370 
stream.pullAmount = result.size; 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

371 
if (stream.pullAmount == 0) { 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

372 
// Done 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

373 
} else if (stream.eof) { 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

374 
// Done 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

375 
} else { 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

376 
read(); 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

377 
} 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

378 
} 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

379 
); 
b6a7ebb05e6b
Add pullAmount precise flow control example
Takeshi Yoshino <tyoshino@google.com>
parents:
112
diff
changeset

380 
}</pre> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

381 
</section> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

382 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

383 
<section class="section" id="writableByteStream"> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

384 
<h2>WritableStream Interface</h2> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

385 
<p> 
128
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

386 
The WritableStream interface defines a protocol for APIs which consume a data stream. 
87
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

387 
The protocol includes: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

388 
<ol> 
127  389 
<li>How to receive data stream</li> 
137  390 
<li>How to notify the writer (data producing code) of completion of writing</li> 
77  391 
<li>How to notify the writer of how much data can be accepted currently</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

392 
</ol> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

393 

123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

394 
By returning a <a>Promise</a> and delaying fulfillment of it, the WritableStream realizes flow control. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

395 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

396 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

397 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

398 
The actual data consumer behind the WritableStream is called a data sink and is identified by <dfn>dataSink</dfn>. 
127  399 
A data sink consumes stream of data and notifies the WritableStream of the cost of data the data sink can newly accept. 
400 
For each data sink, it must be defined how to calculate <a>cost</a> of each object which the data sink can consume. 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

401 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

402 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

403 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

404 
A WritableStream has a onetoone mapping with the associated data sink, and has defined semantics for <a href='#interactingWithDataSink'>interacting with the data sink internally</a>. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

405 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

406 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

407 
<section class="section"> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

408 
<h3>WritableStream interface</h3> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

409 

123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

410 
<dl class="idl" title="interface WritableStream"> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

411 
<dt>attribute DOMString writeEncoding</dt> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

412 
<dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

413 
<p> 
127  414 
A <a>DOMString</a> that represents the label of an encoding [[!EncodingDetermination]] to be passed to <a>dataSink</a> together with data passed to <code>write()</code> method. 
415 
It will be used by <a>dataSink</a> for encoding determination. 

416 
This attribute returns the label last set, or the empty DOMString if never set. 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

417 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

418 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

419 
<section class="note"> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

420 
This parameter is not designed to be specified as an argument of write() since it's not likely to be changed frequently. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

421 
</section> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

422 
</dd> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

423 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

424 
<dt>Promise&lt;unsigned long long> write()</dt> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

425 
<dd> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

426 
<p> 
127  427 
This method writes the specified <var>data</var> to <a>dataSink</a>. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

428 
</p> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

429 

85
885937bdcc17
Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents:
84
diff
changeset

430 
<section class="note"> 
885937bdcc17
Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents:
84
diff
changeset

431 
<p> 
885937bdcc17
Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents:
84
diff
changeset

432 
write() returns a Promise to make it easy for byte stream producing code to react to backpressure. 
885937bdcc17
Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents:
84
diff
changeset

433 
</p> 
885937bdcc17
Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents:
84
diff
changeset

434 
</section> 
885937bdcc17
Fix bug24021. Typo in process pendingWriteQueue
Takeshi Yoshino <tyoshino@google.com>
parents:
84
diff
changeset

435 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

436 
<p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

437 
This method must run the steps below: 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

438 
<ol> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

439 
<li>Let <var>latchedEncoding</var> be the current value of <a href="#widlWritableStreamwriteEncoding">writeEncoding</a></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

440 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

441 
<li><a>Abort wait</a></li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

442 

132
fc2bc870e7a8
cost argument > costOverride
Takeshi Yoshino <tyoshino@google.com>
parents:
131
diff
changeset

443 
<li> 
fc2bc870e7a8
cost argument > costOverride
Takeshi Yoshino <tyoshino@google.com>
parents:
131
diff
changeset

444 
If <var>costOverride</var> argument is specified, let <var>amountToWrite</var> be <var>costOverride</var> argument. 
fc2bc870e7a8
cost argument > costOverride
Takeshi Yoshino <tyoshino@google.com>
parents:
131
diff
changeset

445 
Otherwise, let <var>amountToWrite</var> be the <a>cost</a> of <var>data</var> 
fc2bc870e7a8
cost argument > costOverride
Takeshi Yoshino <tyoshino@google.com>
parents:
131
diff
changeset

446 
</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

447 

129
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

448 
<li>Let <var>writePromise</var> be a newlycreated <a>Promise</a></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

449 

129
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

450 
<li>Let <var>pendingWrite</var> be a newlycreated <a>PendingWriteDescriptor</a></li> 
98
3b89f8cea0fd
More tuple > pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents:
97
diff
changeset

451 
<li>Set <var>pendingWrite.promise</var> to <var>writePromise</var></li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

452 
<li>Set <var>pendingWrite.amount</var> to <var>amountToWrite</var></li> 
98
3b89f8cea0fd
More tuple > pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents:
97
diff
changeset

453 
<li>Push <var>pendingWrite</var> to <a>pendingWriteQueue</a></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

454 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

455 
<li><a>Process pendingWriteQueue</a></li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

456 

129
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

457 
<li> 
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

458 
Run these steps possibly asynchronously: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

459 

109
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

460 
<dl class="switch"> 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

461 
<dt>If <var>data</var> is a <a>DOMString</a></dt> 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

462 
<dd> 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

463 
Write <var>data</var> to <a>dataSink</a> together with <var>latchedEncoding</var> as <var>encoding</var> parameter. 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

464 
Interpretation of <var>latchedEncoding</var> is up to <a>dataSink</a>. 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

465 
</dd> 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

466 
<dt>Otherwise</dt> 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

467 
<dd> 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

468 
Write <var>data</var> to <a>dataSink</a>. 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

469 
</dd> 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

470 
</dl> 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

471 
</li> 
129
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

472 

855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

473 
<li>Return <var>writePromise</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

474 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

475 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

476 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

477 
<p> 
127  478 
WritableStream interface doesn't guarantee that <var>data</var> argument is cloned. 
479 
Modifications made on <var>data</var> argument after <code>write()</code> method call may affect the data written to <a>dataSink</a>. 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

480 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

481 

37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

482 
<dl class="parameters"> 
111
f3c425cc88db
write accepts any data
Takeshi Yoshino <tyoshino@google.com>
parents:
110
diff
changeset

483 
<dt>any data</dt> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

484 
<dd>Data to write.</dd> 
132
fc2bc870e7a8
cost argument > costOverride
Takeshi Yoshino <tyoshino@google.com>
parents:
131
diff
changeset

485 
<dt>optional [Clamp] unsigned long long costOverride</dt> 
115  486 
<dd>Overrides <a>cost</a> of data.</dd> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

487 
</dl> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

488 
</dd> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

489 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

490 
<dt>Promise&lt;unsigned long long> awaitSpaceAvailable()</dt> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

491 
<dd> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

492 
<p> 
127  493 
The returned Promise will be fulfilled with the data <a>cost</a> which <a>dataSink</a> can accept when <a>dataSink</a> becomes able to accept data with any nonzero amount of cost. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

494 
</p> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

495 

0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

496 
<p> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

497 
This method must run the steps below: 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

498 
<ol> 
137  499 
<li><a>Abort awaitSpace</a></li> 
135
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

500 
<li>Set <a>awaitSpacePromise</a> to a newlycreated <a>Promise</a></li> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

501 
<li>Return <a>awaitSpacePromise</a></li> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

502 
</ol> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

503 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

504 
</dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

505 

103
56c80502bb30
Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
102
diff
changeset

506 
<dt>Promise&lt;undefined> writeClose()</dt> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

507 
<dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

508 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

509 
This method tells the WritableStream that no more data will be written to it. 
127  510 
</p> 
511 
<p> 

123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

512 
Once writeClose() has been called on a WritableStream, no further method calls can be made on the WritableStream. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

513 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

514 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

515 
<p> 
103
56c80502bb30
Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
102
diff
changeset

516 
This method must run the steps below: 
56c80502bb30
Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
102
diff
changeset

517 
<ol> 
129
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

518 
<li>Let <var>closePromise</var> be a newlycreated <a>Promise</a></li> 
103
56c80502bb30
Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
102
diff
changeset

519 
<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

520 
<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

521 
<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

522 
<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

523 
</ol> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

524 
</p> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

525 
</dd> 
116  526 

118  527 
<dt>Promise&lt;undefined> writeAbort(optional any reason)</dt> 
116  528 
<dd> 
529 
<p> 

123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

530 
This method tells the WritableStream that no more data will be written to it with indication of error. 
116  531 
The details of the error will be given by <var>reason</var> argument. 
532 
The interpretation of <var>reason</var> is up to <a>dataSink</a>. 

127  533 
</p> 
534 
<p> 

535 
Once this method has been called on a WritableStream, no further method calls can be made on the WritableStream. 

116  536 
</p> 
537 

538 
<p> 

135
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

539 
This method must run these steps: 
116  540 
<ol> 
129
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

541 
<li>Let <var>abortPromise</var> be a newlycreated <a>Promise</a></li> 
135
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

542 
<li> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

543 
Run these steps possibly asynchronously: 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

544 
<ol> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

545 
<li><a>Writeabort</a> <a>dataSink</a> with <var>reason</var></li> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

546 
<li>Wait until <a>dataSink</a> acknowledges the <a>writeabort</a></li> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

547 
<li>Fulfill <var>abortPromise</var> with <code>undefined</code></li> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

548 
</ol> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

549 
</li> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

550 
<li>Return <var>abortPromise</var></li> 
116  551 
</ol> 
552 
</p> 

553 
</dd> 

37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

554 
</dl> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

555 
</section> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

556 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

557 
<section class="section"> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

558 
<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

559 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

560 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

561 
The data sink is the underlying mechanism which a <a>WritableStream</a> interacts with and stores its data in. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

562 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

563 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

564 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

565 
A data sink to which the <a>WritableStream</a> interface writes bytes can be anything which: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

566 
<ol> 
109
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

567 
<li> 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

568 
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

569 
</li> 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

570 
<li> 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

571 
Accepts the EOF signal 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

572 
</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

573 
<li> 
127  574 
Accepts the <dfn>writeabort</dfn> signal with an object parameter named reason. 
116  575 
</li> 
576 
<li> 

123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

577 
Notifies <a>WritableStream</a> of how much data the data sink can newly accept. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

578 
When and how to generate such notifications is up to data sinks. 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

579 
Data sinks must be able to accept data more than it notified <a>WritableStream</a> of. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

580 
</li> 
103
56c80502bb30
Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
102
diff
changeset

581 
<li> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

582 
Notifies <a>WritableStream</a> of that the data sink is gone. 
119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

583 
This signal may mean an error. 
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

584 
If it means an error, an object indicating the details of the error is attached. 
116  585 
</li> 
586 
<li> 

127  587 
Notifies <a>WritableStream</a> of acknowledgement of the EOF signal. 
588 
</li> 

589 
<li> 

123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

590 
Notifies <a>WritableStream</a> of acknowledgement of the writeabort signal with error detail object. 
103
56c80502bb30
Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
102
diff
changeset

591 
</li> 
109
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

592 
<li> 
127  593 
It's defined how to calculate an integer value <dfn>cost</dfn> of each object which the data sink can consume. 
109
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

594 
</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

595 
</ol> 
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 
</section> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

598 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

599 
<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

600 
<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

601 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

602 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

603 
This section defines the internal mechanisms for how the WritableStream interacts with <a>dataSink</a>. 
93
33fa9ecdbe74
A bit tweak on data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents:
92
diff
changeset

604 
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

605 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

606 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

607 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

608 
A WritableStream has an associated integer variable <dfn>spaceAvailable</dfn> which holds the number of bytes that <a>dataSink</a> requested but not yet written to it. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

609 
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

610 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

611 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

612 
<p> 
135
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

613 
A WritableStream has an associated <a>Promise</a> <dfn>awaitSpacePromise</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

614 
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

615 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

616 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

617 
<p> 
137  618 
To <dfn>abort awaitSpace</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

619 
<ol> 
135
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

620 
<li>If <a>awaitSpacePromise</a> is <code>null</code>, terminate these steps</li> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

621 
<li>Let <var>detachedWaitPromise</var> be <a>awaitSpacePromise</a></li> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

622 
<li>Set <a>awaitSpacePromise</a> to <code>null</code></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

623 
<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

624 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

625 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

626 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

627 
<p> 
94
e06bf08768db
Formatting data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents:
93
diff
changeset

628 
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

629 
<ul> 
91
3ed9f08a1f23
Renames for readability
Takeshi Yoshino <tyoshino@google.com>
parents:
90
diff
changeset

630 
<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

631 
<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

632 
<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

633 
</ul> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

634 
</p> 
94
e06bf08768db
Formatting data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents:
93
diff
changeset

635 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

636 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

637 
A WritableStream has an associated queue <dfn>pendingWriteQueue</dfn> which holds <a>PendingWriteDescriptor</a>s. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

638 
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

639 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

640 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

641 
<p> 
127  642 
To <dfn>process pendingWriteQueue</dfn>, run the steps below: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

643 
<ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

644 
<li> 
127  645 
While <a>pendingWriteQueue</a> is not empty, repeat the steps below: 
646 
<ol> 

647 
<li>Let <var>pendingWrite</var> be the head element of <a>pendingWriteQueue</a></li> 

648 
<li> 

649 
<dl class="switch"> 

650 
<dt>If <a>sinkGone</a> is set</dt> 

651 
<dd> 

119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

652 
<ol> 
127  653 
<li>Pop <var>pendingWrite</var> from <a>pendingWriteQueue</a>, and then</li> 
654 
<li>If <var>pendingWrite.promise</var> is not <code>null</code>, reject it with <a>sinkErrorDetail</a></li> 

119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

655 
</ol> 
127  656 
</dd> 
657 
<dt>Otherwise</dt> 

658 
<dd> 

659 
<ol> 

660 
<li>Let <var>amountToAcknowledge</var> be min(<var>pendingWrite.amount</var>  <var>pendingWrite.ackedAmount</var>, <a>spaceAvailable</a>)</li> 

661 
<li>Set <a>spaceAvailable</a> to <a>spaceAvailable</a>  <var>amountToAcknowledge</var></li> 

662 
<li>Set <var>pendingWrite.ackedAmount</var> to <var>pendingWrite.ackedAmount</var> + <var>amountToAcknowledge</var></li> 

663 
<li> 

664 
<dl class="switch"> 

665 
<dt>If <var>pendingWrite.ackedAmount</var> equals to <var>pendingWrite.amount</var></dt> 

666 
<dd> 

667 
<ol> 

668 
<li>Pop <var>pendingWrite</var> from <a>pendingWriteQueue</a></li> 

669 
<li>If <var>pendingWrite.promise</var> is not <code>null</code>, fulfill it with <var>pendingWrite.amount</var></li> 

670 
</ol> 

671 
</dd> 

672 
<dt>Otherwise</dt> 

673 
<dd> 

674 
Exit from this loop 

675 
</dd> 

676 
</dl> 

677 
</li> 

678 
</ol> 

679 
</dd> 

680 
</dl> 

681 
</li> 

682 
</ol> 

683 
</li> 

684 

685 
<li> 

686 
If <a>pendingWriteQueue</a> is empty and <a>spaceAvailable</a> is not 0, run the steps below: 

687 
<ol> 

135
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

688 
<li>If <a>awaitSpacePromise</a> is <code>null</code>, terminate these steps</li> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

689 
<li>Let <var>detachedWaitPromise</var> be <a>awaitSpacePromise</a></li> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

690 
<li>Set <a>awaitSpacePromise</a> to <code>null</code></li> 
127  691 
<li>Fulfill <var>detachedWaitPromise</var> with <a>spaceAvailable</a></li> 
692 
</ol> 

119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

693 
</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

694 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

695 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

696 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

697 
<p> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

698 
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

699 
<ol> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

700 
<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

701 
<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

702 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

703 
</p> 
119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

704 

218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

705 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

706 
A WritableStream has an associated flag <dfn>sinkGone</dfn> which is set when the data sink is gone. 
119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

707 
</p> 
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

708 

218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

709 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

710 
A WritableStream has an associated object <dfn>sinkErrorDetail</dfn> which is initialized to null, and when the data sink is gone, set to the error detail object. 
119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

711 
</p> 
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

712 

218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

713 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

714 
When <a>dataSink</a> notifies the WritableStream of that the data sink is gone, queue a task which runs the steps below: 
119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

715 
<ol> 
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

716 
<li>Set <a>sinkGone</a></li> 
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

717 
<li>Set <a>sinkErrorDetail</a> to the error detail object</li> 
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

718 
<li><a>Process pendingWriteQueue</a></li> 
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

719 
</ol> 
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

720 
</p> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

721 
</section> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

722 
</section> 
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="section" id="readableByteStream"> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

725 
<h2>ReadableStream Interface</h2> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

726 
<p> 
128
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

727 
The ReadableStream interface defines a protocol for APIs which produce a data stream. 
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

728 
This protocol includes: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

729 
<ol> 
137  730 
<li>How to receive read requests from the reader (data consuming code) and pass output data to the reader</li> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

731 
<li>How to transfer data in bulk to another <a>WritableStream</a> (by using the <code>pipe()</code> method)</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

732 
<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

733 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

734 

123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

735 
By returning a <a>Promise</a> and delaying fulfillment of it, the ReadableStream realizes asynchronous data consumption. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

736 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

737 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

738 
<p> 
77  739 
Interfaces introduced in this section provide simple and convenient ways to consume data. 
128
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

740 
They connect arbitrary data stream producer and data consuming code using Promises and method invocations. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

741 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

742 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

743 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

744 
A ReadableStream has a onetoone mapping with an associated data source, and has defined semantics for <a href='#interactingWithDataSource'>interacting with the data source internally</a>. 
128
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

745 
A data source, however, can have a onetomany relationship with ReadableStreams, in cases where <code>fork()</code> is used. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

746 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

747 

77  748 
<section class="section" id="readableByteStreamInterface"> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

749 
<h3>ReadableStream interface</h3> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

750 

123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

751 
<dl class="idl" title="interface ReadableStream"> 
125
98448480356b
ByteStreamReadType > StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents:
124
diff
changeset

752 
<dt>attribute StreamReadType readBinaryAs</dt> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

753 
<dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

754 
<p> 
114
6cd4d6696cb8
Change readExact to readUpTo and make it able to handle nonbyte type data
Takeshi Yoshino <tyoshino@google.com>
parents:
113
diff
changeset

755 
Specifies what data type will be returned by a <code>read()</code> and <code>readUpTo()</code> method call. 
125
98448480356b
ByteStreamReadType > StreamReadType
Takeshi Yoshino <tyoshino@google.com>
parents:
124
diff
changeset

756 
This attribute can be set to any of the supported types in <a>StreamReadType</a>. 
137  757 
<p> 
758 
</p> 

759 
The default value for this attribute is "<code>asis</code>". 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

760 
</p> 
128
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

761 
<p> 
137  762 
Values other than "<code>asis</code>" works only when the data to be read from the ReadableStream represents binary data. 
128
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

763 
</p> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

764 
</dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

765 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

766 
<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

767 
<dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

768 
<p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

769 
Specifies a <a>DOMString</a> that represents the label of an encoding [[!EncodingDetermination]]. 
128
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

770 
If set, it will be used as part of the encoding determination used when processing a <code>read()</code> and <code>readUpTo()</code> method call. 
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

771 
</p> 
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

772 
<p> 
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

773 
This attribute works only when the data to be read from the ReadableStream represents binary data. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

774 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

775 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

776 
<section class="note"> 
128
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

777 
This parameter is not designed to be specified as an argument of the reading methods since it's not likely to be changed frequently. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

778 
</section> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

779 
</dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

780 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

781 
<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

782 
<dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

783 
<p> 
128
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

784 
This attribute provides the ReadableStream with a hint of how much data the reader can consume currently. 
137  785 
</p> 
786 
<p> 

128
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

787 
Each implementation of the ReadableStream must initialize the value of pullAmount on construction. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

788 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

789 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

790 
<p> 
137  791 
When this attribute is set, the user agent must <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

792 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

793 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

794 
<section class="note"> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

795 
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

796 
</section> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

797 
<section class="note"> 
128
56491a744f4d
ReadableStream rewriting
Takeshi Yoshino <tyoshino@google.com>
parents:
127
diff
changeset

798 
It's possible that the cost of data received by <code>read()</code> is more than the pullAmount value. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

799 
</section> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

800 
</dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

801 

124
9dc273a030cc
 ByteStreamReadResult > StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents:
123
diff
changeset

802 
<dt>Promise&lt;StreamReadResult> readUpTo()</dt> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

803 
<dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

804 
<p> 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

805 
This method reads binary data from the ReadableStream. 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

806 
The returned <a>Promise</a> is fulfilled when any of the following conditions is met: 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

807 
<ul> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

808 
<li>The total size of produced bytes becomes equal to <var></var></li> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

809 
<li>The EOF is reached</li> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

810 
</ul> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

811 
The <a>cost</a> of data returned by this method can be less than <var>size</var> when data cannot be fully converted into the type specified by <a href="#widlReadableStreamreadBinaryAs">readBinaryAs</a> or the EOF is reached. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

812 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

813 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

814 
<p> 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

815 
This method must run these steps: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

816 
<ol> 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

817 
<li>If <a href="#widlReadableStreamreadBinaryAs">readBinaryAs</a> is "<code>asis</code>", return a <a>Promise</a> rejected with a "<code><a>SyntaxError</a></code>"</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

818 

133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

819 
<li>If <a>pendingRead</a> is not <code>null</code>, return a <a>Promise</a> rejected with an "<code><a>InvalidStateError</a></code>"</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

820 

136
351c58f63ce5
pendingRead may be null when returning pendingRead.promise. Use local
Takeshi Yoshino <tyoshino@google.com>
parents:
135
diff
changeset

821 
<li>Let <var>readPromise</var> be a newlycreated <a>Promise</a></li> 
351c58f63ce5
pendingRead may be null when returning pendingRead.promise. Use local
Takeshi Yoshino <tyoshino@google.com>
parents:
135
diff
changeset

822 

133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

823 
<li>Set <a>pendingRead</a> to a newlycreated <a>PendingReadDescriptor</a></li> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

824 

ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

825 
<li>Set <a>pendingRead</a>.<var>binaryAs</var> to the current value of <a href="#widlReadableStreamreadBinaryAs">readBinaryAs</a></li> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

826 
<li>Set <a>pendingRead</a>.<var>encoding</var> to the current value of <a href="#widlReadableStreamreadEncoding">readEncoding</a></li> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

827 
<li>Set <a>pendingRead</a>.<var>size</var> to <var>size</var></li> 
136
351c58f63ce5
pendingRead may be null when returning pendingRead.promise. Use local
Takeshi Yoshino <tyoshino@google.com>
parents:
135
diff
changeset

828 
<li>Set <a>pendingRead</a>.<var>promise</var> to <var>readPromise</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

829 

114
6cd4d6696cb8
Change readExact to readUpTo and make it able to handle nonbyte type data
Takeshi Yoshino <tyoshino@google.com>
parents:
113
diff
changeset

830 
<li>Set <a>readUpToPullAmount</a> to <var>size</var></li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

831 
<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

832 

107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

833 
<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

834 

136
351c58f63ce5
pendingRead may be null when returning pendingRead.promise. Use local
Takeshi Yoshino <tyoshino@google.com>
parents:
135
diff
changeset

835 
<li>Return <var>readPromise</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

836 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

837 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

838 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

839 
<dl class="parameters"> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

840 
<dt>[Clamp] unsigned long long size</dt> 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

841 
<dd>Upper limit of total cost of data to be read</dd> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

842 
</dl> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

843 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

844 
<section class="note"> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

845 
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

846 
<ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

847 
<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

848 
<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

849 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

850 
</section> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

851 
</dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

852 

124
9dc273a030cc
 ByteStreamReadResult > StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents:
123
diff
changeset

853 
<dt>Promise&lt;StreamReadResult> read()</dt> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

854 
<dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

855 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

856 
This method reads data from the ReadableStream. 
124
9dc273a030cc
 ByteStreamReadResult > StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents:
123
diff
changeset

857 
The speed of reading can be roughly adjusted by using <a href="#widlStreamReadResultpullAmount">pullAmount</a>. 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

858 
<a href="#widlStreamReadResultpullAmount">pullAmount</a> doesn't necessarily limit the size of data being read by this method. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

859 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

860 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

861 
<p> 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

862 
This method must run these steps: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

863 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

864 
<ol> 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

865 
<li>If <a>pendingRead</a> is not <code>null</code>, return a Promise reject with an "<code><a>InvalidStateError</a></code>"</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

866 

136
351c58f63ce5
pendingRead may be null when returning pendingRead.promise. Use local
Takeshi Yoshino <tyoshino@google.com>
parents:
135
diff
changeset

867 
<li>Let <var>readPromise</var> be a newlycreated <a>Promise</a></li> 
351c58f63ce5
pendingRead may be null when returning pendingRead.promise. Use local
Takeshi Yoshino <tyoshino@google.com>
parents:
135
diff
changeset

868 

133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

869 
<li>Set <a>pendingRead</a> to a newlycreated <a>PendingReadDescriptor</a></li> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

870 

ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

871 
<li>Set <a>pendingRead</a>.<var>binaryAs</var> to the current value of <a href="#widlReadableStreamreadBinaryAs">readBinaryAs</a></li> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

872 
<li>Set <a>pendingRead</a>.<var>encoding</var> to the current value of <a href="#widlReadableStreamreadEncoding">readEncoding</a></li> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

873 
<li>Set <a>pendingRead</a>.<var>size</var> to <code>undefined</code></li> 
136
351c58f63ce5
pendingRead may be null when returning pendingRead.promise. Use local
Takeshi Yoshino <tyoshino@google.com>
parents:
135
diff
changeset

874 
<li>Set <a>pendingRead</a>.<var>promise</var> to <var>readPromise</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

875 

107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

876 
<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

877 

107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

878 
<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

879 

136
351c58f63ce5
pendingRead may be null when returning pendingRead.promise. Use local
Takeshi Yoshino <tyoshino@google.com>
parents:
135
diff
changeset

880 
<li>Return <var>readPromise</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

881 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

882 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

883 

78  884 
<p> 
83
afed6501a898
moved images, fixed typos, fixed header
fmoussa <feras.moussa@hotmail.com>
parents:
81
diff
changeset

885 
<img src="images/fulfilling.png" alt="How new data is automatically fetched"> 
78  886 
</p> 
887 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

888 
<section class="note"> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

889 
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

890 
<ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

891 
<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

892 
<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

893 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

894 
</section> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

895 
</dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

896 

124
9dc273a030cc
 ByteStreamReadResult > StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents:
123
diff
changeset

897 
<dt>Promise&lt;StreamReadResult> pipe()</dt> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

898 
<dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

899 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

900 
This method bulk transfers bytes from the ReadableStream to another <a>WritableStream</a>. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

901 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

902 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

903 
<section class="note"> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

904 
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

905 
</section> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

906 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

907 
<section class="note"> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

908 
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

909 
</section> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

910 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

911 
<p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

912 
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

913 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

914 
<ol> 
130
e8f1ead18653
Throw > return a Promise rejected with
Takeshi Yoshino <tyoshino@google.com>
parents:
129
diff
changeset

915 
<li>If <a>readPending</a> is set, return a <a>Promise</a> rejected with an "<code><a>InvalidStateError</a></code>"</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

916 
<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

917 

137  918 
<li>Run <a>abort awaitSpace</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

919 

107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

920 
<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

921 

107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

922 
<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

923 

129
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

924 
<li>Let <var>pipePromise</var> be a newlycreated <a>Promise</a></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

925 
<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

926 

107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

927 
<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

928 
<li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

929 
Repeat the steps below: 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

930 
<ul> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

931 
<li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

932 
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

933 
<dl class="switch"> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

934 
<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

935 
<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

936 
<dt>Otherwise</dt> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

937 
<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

938 
</dl> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

939 
<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

940 
<li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

941 
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

942 
<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

943 
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

944 
</section> 
7421b9a22a7e
More bug fix in pipe(). numBytesRequested is used where numBytesSpaceAvailable must be used.
Takeshi Yoshino <tyoshino@google.com>
parents:
99
diff
changeset

945 
</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

946 
<li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

947 
<dl class="switch"> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

948 
<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

949 
<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

950 
<dt>Otherwise</dt> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

951 
<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

952 
</dl> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

953 
</li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

954 
<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

955 
<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

956 

129
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

957 
<li>Let <var>pendingWrite</var> be a newlycreated <a>PendingWriteDescriptor</a></li> 
98
3b89f8cea0fd
More tuple > pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents:
97
diff
changeset

958 
<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

959 
<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

960 
<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

961 

107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

962 
<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

963 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

964 
<li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

965 
<dl class="switch"> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

966 
<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

967 
<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

968 
<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

969 
<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

970 
</dl> 
102
a176607d4c3a
TODO about pipe() finish timing
Takeshi Yoshino <tyoshino@google.com>
parents:
101
diff
changeset

971 
<section class="note"> 
a176607d4c3a
TODO about pipe() finish timing
Takeshi Yoshino <tyoshino@google.com>
parents:
101
diff
changeset

972 
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

973 
</section> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

974 
</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

975 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

976 
</li> 
137  977 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

978 
<li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

979 
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

980 
<dl class="switch"> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

981 
<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

982 
<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

983 
<dt>Otherwise</dt> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

984 
<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

985 
</dl> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

986 
<ol> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

987 
<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

988 
<li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

989 
<dl class="switch"> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

990 
<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

991 
<dd> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

992 
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

993 
<section class="note"> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

994 
If <a href="#widlReadableStreampullAmount">pullAmount</a> is set to 0, pipe() transfers data in pull style. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

995 
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

996 
</section> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

997 
<section class="note"> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

998 
Setting <a href="#widlReadableStreampullAmount">pullAmount</a> to a small value doesn't have an effect of throttling the pace of pipe(). 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

999 
</section> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1000 
</dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1001 
<dt>Otherwise</dt> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

1002 
<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

1003 
</dl> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1004 
</li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

1005 
<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

1006 
<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

1007 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1008 
</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1009 
</ul> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1010 
</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1011 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1012 
<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

1013 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1014 
<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

1015 

129
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

1016 
<li>Let <var>result</var> be a newlycreated <a>StreamReadResult</a></li> 
124
9dc273a030cc
 ByteStreamReadResult > StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents:
123
diff
changeset

1017 
<li>Set <var>result</var>.<a href="#widlStreamReadResultdata">data</a> to <code>undefined</code>. 
9dc273a030cc
 ByteStreamReadResult > StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents:
123
diff
changeset

1018 
<li>Set <var>result</var>.<a href="#widlStreamReadResulteof">eof</a> to <code>true</code> if <a>eofReached</a></li> 
9dc273a030cc
 ByteStreamReadResult > StreamReadResult
Takeshi Yoshino <tyoshino@google.com>
parents:
123
diff
changeset

1019 
<li>Set <var>result</var>.<a href="#widlStreamReadResultamountConsumed">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

1020 
<li> 
101
7da4a886ff9f
More pipe() bug fixes
Takeshi Yoshino <tyoshino@google.com>
parents:
100
diff
changeset

1021 
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

1022 
<section class="note"> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

1023 
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

1024 
</section> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1025 
</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1026 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1027 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1028 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1029 
<dl class="parameters"> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1030 
<dt>WritableStream destination</dt> 
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1031 
<dd>Destination <a>WritableStream</a>.</dd> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1032 
<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

1033 
<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

1034 
</dl> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1035 
</dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1036 

123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1037 
<dt>ReadableStream fork()</dt> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1038 
<dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1039 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1040 
This method creates a new ReadableStream which refers to the same <a>dataSource</a> as the current ReadableStream. 
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1041 
Data sources are range reference counted so that a range in a data source is freed only when all the ReadableStreams sharing the data source finish consuming it. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1042 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1043 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1044 
<p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1045 
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

1046 
<ol> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1047 
<li>Let <var>branch</var> be a new ReadableStream which refers to <a>dataSource</a> and has the same <a>amountRequested</a> value, <a>readDataBuffer</a> contents and <a>eofReached</a> value as the current ReadableStream.</li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

1048 
<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

1049 
<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

1050 
</ol> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1051 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1052 
</dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1053 

118  1054 
<dt>Promise&lt;undefined> readAbort(optional any reason)</dt> 
117  1055 
<dd> 
1056 
<p> 

123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1057 
This method tells the ReadableStream that no more data will be read from it optionally with indication of error. 
117  1058 
The details of the error will be given by <var>reason</var> argument. 
1059 
The interpretation of <var>reason</var> is up to <a>dataSource</a>. 

135
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

1060 
</p> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

1061 
<p> 
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

1062 
Once this method has been called on a ReadableStream, no further method calls can be made on the ReadableStream. 
117  1063 
</p> 
1064 

1065 
<p> 

135
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

1066 
This method must run these steps: 
117  1067 
<ol> 
129
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

1068 
<li>Let <var>abortPromise</var> be a newlycreated <a>Promise</a></li> 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

1069 
<li> 
135
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

1070 
Run these steps possibly asynchronously: 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

1071 
<ol> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

1072 
<li><a>Readabort</a> <a>dataSource</a> with <var>reason</var></li> 
135
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

1073 
<li>Wait until <a>dataSource</a> acknowledges the <a>readabort</a></li> 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

1074 
<li>Fulfill <var>abortPromise</var> with <code>undefined</code></li> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

1075 
</ol> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

1076 
</li> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

1077 
<li>Return <var>abortPromise</var></li> 
117  1078 
</ol> 
1079 
</p> 

1080 
</dd> 

37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

1081 
</dl> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

1082 
</section> 
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

1083 

76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1084 
<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

1085 
<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

1086 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1087 
<p> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1088 
A data source produces the bytes to be consumed via the <a>ReadableStream</a> interface instances. 
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1089 
A <a>ReadableStream</a> retrieves bytes from an associated data source. 
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1090 
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="#widlReadableStreamforkReadableStream">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

1091 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1092 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1093 
<p> 
95
af7f31ca4da3
Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents:
94
diff
changeset

1094 
A <dfn>data source</dfn> can be anything that: 
af7f31ca4da3
Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents:
94
diff
changeset

1095 
<ul> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1096 
<li> 
120
1eab5673997f
Break at the end of a sentence
Takeshi Yoshino <tyoshino@google.com>
parents:
114
diff
changeset

1097 
Produces bytes. 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1098 
Newly produced bytes will be delivered to the associated <a>ReadableStream</a>. 
95
af7f31ca4da3
Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents:
94
diff
changeset

1099 
</li> 
af7f31ca4da3
Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents:
94
diff
changeset

1100 
<li> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1101 
Notifies <a>ReadableStream</a> of the EOF signal. 
119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

1102 
This signal may mean an error. 
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

1103 
If it means an error, an object indicating the details of the error is attached. 
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

1104 
</li> 
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

1105 
<li> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1106 
Accepts requests for production of bytes from a <a>ReadableStream</a>. 
120
1eab5673997f
Break at the end of a sentence
Takeshi Yoshino <tyoshino@google.com>
parents:
114
diff
changeset

1107 
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

1108 
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

1109 
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

1110 
Requests and delivery of bytes don't need to 1to1 correspond. 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1111 
Data sources may produce bytes and send to <a>ReadableStream</a> unsolicitedly without receiving any retrieval request. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1112 
</li> 
104
69234a5f02a6
Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
103
diff
changeset

1113 
<li> 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1114 
Accepts and acknowledges readabort signal which means the associated <a>ReadableStream</a> has completed consuming bytes from this data source optionally with indication of any error. 
117  1115 
</li> 
95
af7f31ca4da3
Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents:
94
diff
changeset

1116 
</ul> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1117 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1118 

63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1119 
<p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1120 
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

1121 
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

1122 
<ul> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1123 
<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

1124 
<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

1125 
<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

1126 
<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

1127 
<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

1128 
</ul> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1129 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1130 

87
dcf26e7c77fe
Break at the end of each sentence.
< 