author  Takeshi Yoshino <tyoshino@google.com> 
Thu, 30 Jan 2014 10:57:24 +0900  
changeset 146  b58855161982 
parent 145  1e237f753a38 
child 147  be2de4c87594 
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 

145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

383 
<section class="section" id="writableStream"> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

384 
<h2>WritableStream</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> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

398 
The actual data consumer behind the WritableStream is called a <a href="#dataSinkModel">data sink</a> 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"> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
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 

145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

441 
<li><a>Abort awaitSpace</a></li> 
76
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> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

458 
Run the steps below 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> 

145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

512 
Once this method 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> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

519 
<li> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

520 
Run the steps below possibly asynchronously: 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

521 
<ol> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

522 
<li>Send the <a>write EOF</a> signal to <a>dataSink</a></li> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

523 
<li>Wait until <a>dataSink</a> acknowledges the <a>write EOF</a></li> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

524 
<li>Fulfill <var>closePromise</var> with <code>undefined</code></li> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

525 
</ol> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

526 
</li> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

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

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

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

530 
</dd> 
116  531 

118  532 
<dt>Promise&lt;undefined> writeAbort(optional any reason)</dt> 
116  533 
<dd> 
534 
<p> 

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

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

127  538 
</p> 
539 
<p> 

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

116  541 
</p> 
542 

543 
<p> 

138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

544 
This method must run the steps below: 
116  545 
<ol> 
129
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

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

547 
<li> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

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

549 
<ol> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

550 
<li>Send the <a>write abort</a> signal to <a>dataSink</a> with <var>reason</var></li> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

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

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

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

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

555 
<li>Return <var>abortPromise</var></li> 
116  556 
</ol> 
557 
</p> 

558 
</dd> 

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

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

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

561 

145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

562 
<section class="section" id="dataSinkModel"> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

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

564 

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

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

566 
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

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

568 

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

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

570 
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

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

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

573 
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

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

575 
<li> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

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

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

578 
<li> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

579 
Accepts the <dfn>write abort</dfn> signal with an object parameter named <var>reason</var>. 
116  580 
</li> 
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 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

583 
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

584 
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

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

586 
<li> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

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

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

589 
If it means an error, an object indicating the details of the error is attached. 
116  590 
</li> 
591 
<li> 

145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

592 
Notifies <a>WritableStream</a> of acknowledgement of the <a>write EOF</a> signal. 
127  593 
</li> 
594 
<li> 

145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

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

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

597 
<li> 
127  598 
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

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

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

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

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

603 

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

604 
<section class="section" id='interactingWithDataSink'> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

605 
<h2>Interacting with the Data Sink</h2> 
76
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 
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

609 
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

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> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

613 
A WritableStream has an associated integer variable <dfn>spaceAvailable</dfn> which holds the cost of data 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

614 
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

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> 
135
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

618 
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

619 
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

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

621 

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

622 
<p> 
137  623 
To <dfn>abort awaitSpace</dfn>, run the steps below: 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

624 

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

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

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

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

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

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

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

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

632 

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

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

634 
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

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

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

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

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

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

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

641 

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

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

643 
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

644 
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

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

646 

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

647 
<p> 
127  648 
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

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

650 
<li> 
127  651 
While <a>pendingWriteQueue</a> is not empty, repeat the steps below: 
652 
<ol> 

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

654 
<li> 

655 
<dl class="switch"> 

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

657 
<dd> 

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

658 
<ol> 
127  659 
<li>Pop <var>pendingWrite</var> from <a>pendingWriteQueue</a>, and then</li> 
660 
<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

661 
</ol> 
127  662 
</dd> 
663 
<dt>Otherwise</dt> 

664 
<dd> 

665 
<ol> 

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

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

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

669 
<li> 

670 
<dl class="switch"> 

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

672 
<dd> 

673 
<ol> 

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

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

676 
</ol> 

677 
</dd> 

678 
<dt>Otherwise</dt> 

679 
<dd> 

680 
Exit from this loop 

681 
</dd> 

682 
</dl> 

683 
</li> 

684 
</ol> 

685 
</dd> 

686 
</dl> 

687 
</li> 

688 
</ol> 

689 
</li> 

690 

691 
<li> 

138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

692 
If <a>pendingWriteQueue</a> is empty and <a>spaceAvailable</a> is not 0 and <a>awaitSpacePromise</a> is not <code>null</code>, run the steps below: 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

693 

127  694 
<ol> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

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

696 
<li>Set <a>awaitSpacePromise</a> to <code>null</code></li> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

697 
<li>Fulfill <var>detachedPromise</var> with <a>spaceAvailable</a></li> 
127  698 
</ol> 
119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

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

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

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

702 

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

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

704 
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

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

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

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

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

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

710 

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

711 
<p> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

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

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

714 

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

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

716 
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

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

718 

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

719 
<p> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

720 
When <a>dataSink</a> notifies the WritableStream of that the <a>data sink is gone</a>, 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

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

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

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

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

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

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

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

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

729 

145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

730 
<section class="section" id="readableStream"> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

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

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

733 
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

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

735 
<ol> 
137  736 
<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

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

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

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

740 

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

741 
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

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

743 

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

744 
<p> 
77  745 
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

746 
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

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

748 

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

749 
<p> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

750 
A ReadableStream has a onetoone mapping with an associated <a href="#dataSourceModel">data source</a>, 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

751 
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

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

753 

145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

754 
<section class="section" id="readableStreamInterface"> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

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

756 

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

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

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

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

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

761 
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

762 
This attribute can be set to any of the supported types in <a>StreamReadType</a>. 
137  763 
<p> 
764 
</p> 

765 
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

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

767 
<p> 
137  768 
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

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

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

771 

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

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

773 
<dd> 
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 
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

776 
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

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

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

779 
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

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

781 

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

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

783 
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

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

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

786 

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

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

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

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

790 
This attribute provides the ReadableStream with a hint of how much data the reader can consume currently. 
137  791 
</p> 
792 
<p> 

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

793 
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

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

795 

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

796 
<p> 
137  797 
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

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

799 

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

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

801 
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

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

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

804 
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

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

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

807 

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

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

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

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

811 
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

812 
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

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

814 
<li>The total size of produced bytes becomes equal to <var></var></li> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

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

816 
</ul> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

817 
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 <a>read EOF</a> is reached. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

819 

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

820 
<p> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

821 
This method must 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

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

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

824 

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

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

826 

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

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

828 

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

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

830 

146
b58855161982
 pendingRead member reordering
Takeshi Yoshino <tyoshino@google.com>
parents:
145
diff
changeset

831 
<li>Set <a>pendingRead</a>.<var>promise</var> to <var>readPromise</var></li> 
b58855161982
 pendingRead member reordering
Takeshi Yoshino <tyoshino@google.com>
parents:
145
diff
changeset

832 
<li>Set <a>pendingRead</a>.<var>remaining</var> to <var>size</var></li> 
b58855161982
 pendingRead member reordering
Takeshi Yoshino <tyoshino@google.com>
parents:
145
diff
changeset

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

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

835 
<li>Set <a>pendingRead</a>.<var>encoding</var> to the current value of <a href="#widlReadableStreamreadEncoding">readEncoding</a></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

836 

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

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

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

839 

138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

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

841 

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

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

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

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

845 

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

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

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

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

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

850 

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

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

852 
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

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

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

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

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

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

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

859 

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

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

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

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

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

864 
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

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

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

867 

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

868 
<p> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

869 
This method must 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

870 

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

871 
<ol> 
146
b58855161982
 pendingRead member reordering
Takeshi Yoshino <tyoshino@google.com>
parents:
145
diff
changeset

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

873 

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

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

875 

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

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

877 

146
b58855161982
 pendingRead member reordering
Takeshi Yoshino <tyoshino@google.com>
parents:
145
diff
changeset

878 
<li>Set <a>pendingRead</a>.<var>promise</var> to <var>readPromise</var></li> 
b58855161982
 pendingRead member reordering
Takeshi Yoshino <tyoshino@google.com>
parents:
145
diff
changeset

879 
<li>Set <a>pendingRead</a>.<var>remaining</var> to <code>undefined</code></li> 
b58855161982
 pendingRead member reordering
Takeshi Yoshino <tyoshino@google.com>
parents:
145
diff
changeset

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

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

882 
<li>Set <a>pendingRead</a>.<var>encoding</var> to the current value of <a href="#widlReadableStreamreadEncoding">readEncoding</a></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

883 

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

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

885 

138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

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

887 

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

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

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

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

891 

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

893 
<img src="images/fulfilling.png" alt="How new data is automatically fetched"> 
78  894 
</p> 
895 

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

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

897 
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

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

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

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

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

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

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

904 

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

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

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

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

908 
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

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

912 
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

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

914 

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

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

916 
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

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

918 

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

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

920 
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

921 

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

922 
<ol> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

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

924 

138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

925 
<li>Set <var>pipePromise</var> be a newlycreated <a>Promise</a></li> 
137  926 

138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

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

928 

146
b58855161982
 pendingRead member reordering
Takeshi Yoshino <tyoshino@google.com>
parents:
145
diff
changeset

929 
<li>Set <a>pendingRead</a>.<var>promise</var> to <var>pipePromise</var></li> 
b58855161982
 pendingRead member reordering
Takeshi Yoshino <tyoshino@google.com>
parents:
145
diff
changeset

930 
<li>Set <a>pendingRead</a>.<var>remaining</var> to <var>size</var> argument</li> 
b58855161982
 pendingRead member reordering
Takeshi Yoshino <tyoshino@google.com>
parents:
145
diff
changeset

931 
<li>Set <a>pendingRead</a>.<var>destination</var> to <var>destination</var> argument</li> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

932 
<li>Set <a>pendingRead</a>.<var>binaryAs</var> to <code>undefined</code></li> 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

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

934 

144  935 
<li>Set <a>totalAmountTransferred</a> to 0</li> 
936 

138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

937 
<li><a>Wait for destination</a> possibly asynchronously</li> 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

938 

6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

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

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

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

942 

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

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

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

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

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

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

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

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

950 

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

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

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

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

954 
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

955 
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

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

957 

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

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

959 
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

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

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

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

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

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

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

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

967 

118  968 
<dt>Promise&lt;undefined> readAbort(optional any reason)</dt> 
117  969 
<dd> 
970 
<p> 

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

971 
This method tells the ReadableStream that no more data will be read from it optionally with indication of error. 
117  972 
The details of the error will be given by <var>reason</var> argument. 
973 
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

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

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

976 
Once this method has been called on a ReadableStream, no further method calls can be made on the ReadableStream. 
117  977 
</p> 
978 

979 
<p> 

138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

980 
This method must run the steps below: 
117  981 
<ol> 
129
855e24afba79
 new > newlycreate
Takeshi Yoshino <tyoshino@google.com>
parents:
128
diff
changeset

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

983 
<li> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

984 
Run the steps below possibly asynchronously: 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

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

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

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

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

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

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

991 
<li>Return <var>abortPromise</var></li> 
117  992 
</ol> 
993 
</p> 

994 
</dd> 

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

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

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

997 

145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

998 
<section class="section" id='dataSourceModel'> 
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

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

1000 

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

1001 
<p> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1002 
A data source produces data stream to be consumed via the <a>ReadableStream</a> interface instances. 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1003 
A <a>ReadableStream</a> retrieves data from an associated data source. 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1004 
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

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

1006 

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

1007 
<p> 
95
af7f31ca4da3
Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents:
94
diff
changeset

1008 
A <dfn>data source</dfn> can be anything that: 
af7f31ca4da3
Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents:
94
diff
changeset

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

1010 
<li> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1011 
Produces data. 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1012 
Newly produced data will be delivered to the associated <a>ReadableStream</a>. 
119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

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

1014 
<li> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1015 
Notifies <a>ReadableStream</a> of the <dfn>read EOF</dfn> signal. 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1016 
This signal may include indication of an error. 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1017 
When it indicates an error, an object which represents the details of the error is attached. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1018 
</li> 
104
69234a5f02a6
Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
103
diff
changeset

1019 
<li> 
138
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1020 
Accepts requests for production of data from a <a>ReadableStream</a>. 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1021 
A data production request consists of an integer indicating the total cost of data to produce in addition to already requested ones. 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1022 
Interpretation of the request is up to each data source. 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1023 
Data sources may respond to retrieval requests with data larger than requested. 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1024 
Requests and delivery of data don't need to 1to1 correspond. 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1025 
Data sources may produce data and send to <a>ReadableStream</a> unsolicitedly without receiving any retrieval request. 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1026 
</li> 
6cc871794be1
 refactored pipe algorithm and merged with ones for read() and readUpTo()
Takeshi Yoshino <tyoshino@google.com>
parents:
137
diff
changeset

1027 
<li> 
139  1028 
Accepts and acknowledges <dfn>readabort</dfn> signal which means the associated <a>ReadableStream</a> has completed consuming data from this data source optionally with indication of any error. 
117  1029 
</li> 
95
af7f31ca4da3
Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents:
94
diff
changeset

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

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

1032 

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

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

1034 
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

1035 
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

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

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

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

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

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

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

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

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

1044 

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

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

1046 
When <a href="#widlReadableStreamforkReadableStream">fork()</a> is called, a new reader is registered to the original <a>ReadableStream</a>'s data source and the new <a>ReadableStream</a> uses read() method to fetch data from it. 
87
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

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

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

1049 

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

1050 
<section class="section" id="interactingWithDataSource"> 
145
1e237f753a38
Almost finished clean up / bug fixes related to the read/pipe refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
144
diff
changeset

1051 
<h2>Interacting with the Data Source</h2> 
87
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

1052 

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

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

1054 
This interface is designed to work even if operations on <a>dataSource</a> are asynchronous. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1055 
If <a>dataSource</a> is synchronously accessible, some of the algorithms can be simplified. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

1057 

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

1058 
<p> 
139  1059 
A <a>ReadableStream</a> has an associated <a>data source</a> referred by <dfn>dataSource</dfn> from which the ReadableStream retrieves data. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1060 
The data source model is explained in <a href="#h2_data_source">this section</a>. 
123
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1061 
A data source can be shared by multiple ReadableStream instances when <code>fork()</code> is used. 
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1062 
A ReadableStream is registered with a data source on construction and given a reader ID. 
2c23cbb3665f
Revert name back to Readable/WritableStream
Takeshi Yoshino <tyoshino@google.com>
parents:
122
diff
changeset

1063 
The <a>dataSource</a> of a ReadableStream refers to its data source, and <dfn>readerId</dfn> of a ReadableStream refers to its reader ID. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

1065 

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

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

1067 
A ReadableStream has the following internal mechanisms: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

1069 

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

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

1071 
An associated flag <dfn>readPending</dfn> which prevents multiple read operations from being run. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1072 
This flag is set to false on construction. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

1074 

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

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

1076 
An associated integer variable <dfn>readUpToPullAmount</dfn> which temporarily overrides <a href="#widlReadableStreampullAmount">pullAmount</a> if necessary for a <code>readUpTo()</code> method call. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1077 
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

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

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

1080 
An associated integer variable <dfn>pipePullAmount</dfn> which temporarily overrides <a href="#widlReadableStreampullAmount">pullAmount</a> if necessary for a <code>pipe()</code> method call. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1081 
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

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

1083 

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

1084 
<p> 
141  1085 
An associated integer variable <dfn>amountRequested</dfn> which holds the cost of data being retrieved from the <a>dataSource</a>. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1086 
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

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

1088 
<p> 
141  1089 
An associated integer variable <dfn>amountBeingReturned</dfn> which holds the cost of data consumed on the last read operation. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1090 
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

1091 

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

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

1093 
amountBeingReturned delays replenishment of pullAmount until the next read()/pipe() operation is made. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

1096 

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

1097 
<p> 
141  1098 
An associated queue <dfn>readDataBuffer</dfn> which holds data retrieved from <a>dataSource</a>. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1099 
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

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

1101 

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

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

1103 
<img src="images/readdatabuffer.png" alt="Read data buffer related variables"> 
78  1104 
</p> 
1105 

1106 
<p> 

144  1107 
An associated binary data queue <dfn>splicedBinaryBuffer</dfn> which holds binary data spliced from <a>readDataBuffer</a>. 
143  1108 
THis queue is initialized to an empty queue on construction. 
1109 
</p> 

1110 

1111 
<p> 

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

1112 
A struct type <dfn>PendingReadDescriptor</dfn> has the following members: 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

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

1114 
<li>A <a>Promise</a> <var>promise</var></li> 
146
b58855161982
 pendingRead member reordering
Takeshi Yoshino <tyoshino@google.com>
parents:
145
diff
changeset

1115 
<li>An integer <var>remaining</var></li> 
b58855161982
 pendingRead member reordering
Takeshi Yoshino <tyoshino@google.com>
parents:
145
diff
changeset

1116 
<li>A <a>WritableStream</a> <var>destination</var></li> 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

1117 
<li>A <a>DOMString</a> <var>binaryAs</var></li> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

1118 
<li>A <a>DOMString</a> <var>encoding</var></li> 
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

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

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

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

1122 
A WritableStream has an associated <a>PendingReadDescriptor</a> <dfn>pendingRead</dfn>. 
143  1123 
This variable is initialized to <code>null</code> on construction. 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

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

1125 

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

1126 
<p> 
143  1127 
An associated flag <dfn>eofReached</dfn> which indicates that the <a>read EOF</a> was received from the <a>dataSource</a>. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1128 
</p> 