author  Takeshi Yoshino <tyoshino@google.com> 
Thu, 30 Jan 2014 15:25:53 +0900  
changeset 155  841bc807e839 
parent 154  e5f35a6d88fe 
child 156  a0e5ee8be17c 
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> 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

439 
<li>If <a>sinkGone</a> is set, return a <a>Promise</a> rejected with <a>sinkGoneReason</a></li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

440 

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

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

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> 
3b89f8cea0fd
More tuple > pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents:
97
diff
changeset

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

453 

153
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

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

455 

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

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

457 
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

458 

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

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

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

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

462 
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

463 
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

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

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

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

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

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

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

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

471 

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

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

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

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

475 

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

476 
<p> 
127  477 
WritableStream interface doesn't guarantee that <var>data</var> argument is cloned. 
478 
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

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

480 

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

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

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

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

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

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

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

488 

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

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

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

491 
<p> 
152  492 
The returned <a>Promise</a> 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

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

494 

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

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

496 
This method must run the steps below: 
153
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

497 

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

498 
<ol> 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

499 
<li>If <a>sinkGone</a> is set, return a <a>Promise</a> rejected with <a>sinkGoneReason</a></li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

500 
<li>If <a>awaitSpacePromise</a> is not <code>null</code>, return <a>awaitSpacePromise</a> and terminate these steps</li> 
153
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

501 
<li>Let <var>newPromise</var> be a newlycreated <a>Promise</a></li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

502 
<li>Set <a>awaitSpacePromise</a> to <var>newPromise</var></li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

503 
<li><a>Check space</a></li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

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

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

506 
</p> 
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 

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

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

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

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

512 
This method tells the WritableStream that no more data will be written to it. 
127  513 
</p> 
514 
<p> 

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

515 
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

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

517 

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

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

519 
This method must run the steps below: 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

520 

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

521 
<ol> 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

522 
<li>Set <var>writeClosePromise</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

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

524 
Run the steps below possibly asynchronously: 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

525 

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

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

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

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

529 
</li> 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

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

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

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

533 
</dd> 
116  534 

118  535 
<dt>Promise&lt;undefined> writeAbort(optional any reason)</dt> 
116  536 
<dd> 
537 
<p> 

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

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

127  541 
</p> 
542 
<p> 

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

116  544 
</p> 
545 

546 
<p> 

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

547 
This method must run the steps below: 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

548 

116  549 
<ol> 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

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

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

552 
Run the steps below possibly asynchronously: 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

553 

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

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

555 
<li>Send the <a>write abort</a> signal to <a>dataSink</a> with <var>reason</var></li> 
135
8bc65bdf4605
 Some reorg of algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
134
diff
changeset

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

557 
</li> 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

558 
<li>Return <var>writeAbortPromise</var></li> 
116  559 
</ol> 
560 
</p> 

561 
</dd> 

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

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

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

564 

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

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

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

567 

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

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

569 
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

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

571 

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

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

573 
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

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

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

576 
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

577 
</li> 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
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 EOF</dfn> signal 
109
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

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

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

582 
Accepts the <dfn>write abort</dfn> signal with an object parameter named <var>reason</var>. 
116  583 
</li> 
584 
<li> 

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

585 
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

586 
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

587 
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

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

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

590 
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

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

592 
If it means an error, an object indicating the details of the error is attached. 
116  593 
</li> 
594 
<li> 

154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

595 
Notifies <a>WritableStream</a> of acknowledgement of data writing with the <a>cost</a> of the data or 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

596 
failure of data writing with an object representing the reason. 
153
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

597 
</li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

598 
<li> 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

599 
Notifies <a>WritableStream</a> of acknowledgement of the <a>write EOF</a> signal or 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

600 
failure with an object representing the reason. 
127  601 
</li> 
602 
<li> 

154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

603 
Notifies <a>WritableStream</a> of acknowledgement of the <a>write abort</a> signal with error detail object or 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

604 
failure with an object representing the reason. 
103
56c80502bb30
Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
102
diff
changeset

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

606 
<li> 
127  607 
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

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

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

612 

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

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

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

615 

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

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

617 
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

618 
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

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

620 

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

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

622 
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

623 
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

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

625 

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

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

627 
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

628 
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

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

630 

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

631 
<p> 
137  632 
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

633 

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

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

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

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

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

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

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

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

641 

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

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

643 
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

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

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

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

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

648 

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

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

650 
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

651 
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

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

653 

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

654 
<p> 
153
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

655 
To <dfn>check space</dfn>, run the steps below: 
152  656 

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

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

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

659 
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

660 

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

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

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

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

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

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

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

669 

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

670 
<p> 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

671 
An associated <a>Promise</a> <dfn>writeClosePromise</dfn>. 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

672 
This variable is initialized to <code>null</code> on construction. 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

673 
</p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

674 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

675 
<p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

676 
An associated <a>Promise</a> <dfn>writeAbortPromise</dfn>. 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

677 
This variable is initialized to <code>null</code> on construction. 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

678 
</p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

679 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

680 
<p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

681 
An associated boolean <dfn>sinkGone</dfn>. 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

682 
This variable is initialized to <code>false</code> on construction. 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

683 
</p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

684 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

685 
<p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

686 
An associated object <dfn>sinkGoneReason</dfn>. 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

687 
This variable is initialized to <code>null</code> on construction. 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

688 
</p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

689 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

690 
<p> 
153
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

691 
When <a>dataSink</a> notified the <a>WritableStream</a> of acknowledgement of data writing with <var>writtenAmount</var> which is the <a>cost</a> of the written data, run the steps below: 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

692 

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

693 
<ol> 
153
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

694 
<li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

695 
<dl class="switch"> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

696 
<dt>If in the event loop</dt> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

697 
<dd>Run the rest of these steps</dd> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

698 
<dt>Otherwise</dt> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

699 
<dd>Queue a task which runs the rest of these steps</dd> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

700 
</dl> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

701 
</li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

702 

c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

703 
<li>Pop the head element from <a>pendingWriteQueue</a>, and let <var>pendingWrite</var> be the element</li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

704 
<li>If <var>pendingWrite.promise</var> is not <code>null</code>, fulfill it with <var>writtenAmount</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

707 

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

708 
<p> 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

709 
When <a>dataSink</a> notified the <a>WritableStream</a> of that <a>data sink is gone</a> with an object <var>reason</var> which represents the reason, run the steps below: 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

710 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

711 
<ol> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

712 
<li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

713 
<dl class="switch"> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

714 
<dt>If in the event loop</dt> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

715 
<dd>Run the rest of these steps</dd> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

716 
<dt>Otherwise</dt> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

717 
<dd>Queue a task which runs the rest of these steps</dd> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

718 
</dl> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

719 
</li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

720 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

721 
<li>Set <a>sinkGone</a></li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

722 
<li>Set <a>sinkGoneReason</a> to <var>reason</var></li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

723 
<li><a>Abort awaitSpace</a></li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

724 
</ol> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

725 
</p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

726 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

727 
<p> 
153
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

728 
When <a>dataSink</a> notified the <a>WritableStream</a> of failure of data writing with an object <var>reason</var> which represents the detail of the error, run the steps below: 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

729 

c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

730 
<ol> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

731 
<li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

732 
<dl class="switch"> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

733 
<dt>If in the event loop</dt> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

734 
<dd>Run the rest of these steps</dd> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

735 
<dt>Otherwise</dt> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

736 
<dd>Queue a task which runs the rest of these steps</dd> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

737 
</dl> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

738 
</li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

739 

c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

740 
<li>Pop the head element from <a>pendingWriteQueue</a>, and let <var>pendingWrite</var> be the element</li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

741 
<li>If <var>pendingWrite.promise</var> is not <code>null</code>, reject it with <var>reason</var></li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

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

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

744 

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

745 
<p> 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

746 
When <a>dataSink</a> acknowledges the <a>write EOF</a>, run the steps below: 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

747 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

748 
<ol> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

749 
<li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

750 
<dl class="switch"> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

751 
<dt>If in the event loop</dt> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

752 
<dd>Run the rest of these steps</dd> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

753 
<dt>Otherwise</dt> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

754 
<dd>Queue a task which runs the rest of these steps</dd> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

755 
</dl> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

756 
</li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

757 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

758 
<li>Fulfill <var>writeClosePromise</var> with <code>undefined</code></li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

759 
</ol> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

760 
</p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

761 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

762 
<p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

763 
When <a>dataSink</a> notifies of failure of the <a>write EOF</a> signal with <var>reason</var>, run the steps below: 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

764 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

765 
<ol> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

766 
<li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

767 
<dl class="switch"> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

768 
<dt>If in the event loop</dt> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

769 
<dd>Run the rest of these steps</dd> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

770 
<dt>Otherwise</dt> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

771 
<dd>Queue a task which runs the rest of these steps</dd> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

772 
</dl> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

773 
</li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

774 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

775 
<li>Reject <var>writeClosePromise</var> with <var>reason</var></li> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

776 
</ol> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

777 
</p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

778 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

779 
<p> 
155
841bc807e839
Remove unnecessary task queuing
Takeshi Yoshino <tyoshino@google.com>
parents:
154
diff
changeset

780 
When <a>dataSink</a> acknowledges the <a>write abort</a>, fulfill <var>writeAbortPromise</var> with <code>undefined</code> 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

781 
</p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

782 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

783 
<p> 
155
841bc807e839
Remove unnecessary task queuing
Takeshi Yoshino <tyoshino@google.com>
parents:
154
diff
changeset

784 
When <a>dataSink</a> notifies of failure of the <a>write abort</a> signal with <var>reason</var>, reject <var>writeAbortPromise</var> with <var>reason</var> 
154
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

785 
</p> 
e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

786 

e5f35a6d88fe
More rewriting on writeAbort/Close
Takeshi Yoshino <tyoshino@google.com>
parents:
153
diff
changeset

787 
<p> 
153
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

788 
When <a>dataSink</a> requests <var>amountNewlyRequested</var> more data, run the steps below: 
119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

789 

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

790 
<ol> 
153
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

791 
<li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

792 
<dl class="switch"> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

793 
<dt>If in the event loop</dt> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

794 
<dd>Run the rest of these steps</dd> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

795 
<dt>Otherwise</dt> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

796 
<dd>Queue a task which runs the rest of these steps</dd> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

797 
</dl> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

798 
</li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

799 

c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

800 
<li>Set <a>spaceAvailable</a> to <a>spaceAvailable</a> + <var>amountNewlyRequested</var></li> 
c01aad6a7b78
Change the role of the Promise returned by write()
Takeshi Yoshino <tyoshino@google.com>
parents:
152
diff
changeset

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

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

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

804 
</section> 
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 

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

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

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

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

810 
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

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

812 
<ol> 
137  813 
<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

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

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

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

817 

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

818 
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

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

820 

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

821 
<p> 
77  822 
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

823 
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

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

825 

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

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

827 
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

828 
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

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

830 

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

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

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

833 

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

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

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

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

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

838 
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

839 
This attribute can be set to any of the supported types in <a>StreamReadType</a>. 
137  840 
<p> 
841 
</p> 

842 
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

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

844 
<p> 
137  845 
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

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

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

848 

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

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

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

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

852 
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

853 
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

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

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

856 
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

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

858 

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

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

860 
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

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

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

863 

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

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

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

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

867 
This attribute provides the ReadableStream with a hint of how much data the reader can consume currently. 
137  868 
</p> 
869 
<p> 

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

870 
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

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

872 

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

873 
<p> 
149
7d67846b9a4d
Renaming retrieve data > request data production
Takeshi Yoshino <tyoshino@google.com>
parents:
148
diff
changeset

874 
When this attribute is set, the user agent must <a>request data production</a>. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

876 

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

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

878 
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

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

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

881 
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

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

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

884 

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

885 
<dt>Promise&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

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

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

888 
This method reads binary data from the ReadableStream. 
152  889 
The returned <a>Promise</a> will be fulfilled when any of the following conditions is met: 
133
ecde9f975249
Split data output code from read() and readUpTo() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
132
diff
changeset

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

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

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

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

894 
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

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

896 

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

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

898 
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

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

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

901 

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

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

903 

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

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

905 

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

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

907 

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

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

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

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

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

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

913 

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

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

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

916 

149
7d67846b9a4d
Renaming retrieve data > request data production
Takeshi Yoshino <tyoshino@google.com>
parents:
148
diff
changeset

917 
<li><a>Request data production</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

918 

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

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

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

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

922 

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

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

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

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

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

927 

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

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

929 
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

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

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

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

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

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

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

936 

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

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

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

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

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

941 
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

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

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

944 

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

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

946 
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

947 

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

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

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

950 

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

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

952 

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

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

954 

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

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

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

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

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

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

960 

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

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

962 

149
7d67846b9a4d
Renaming retrieve data > request data production
Takeshi Yoshino <tyoshino@google.com>
parents:
148
diff
changeset

963 
<li><a>Request data production</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

964 

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

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

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

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

968 

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

970 
<img src="images/fulfilling.png" alt="How new data is automatically fetched"> 
78  971 
</p> 
972 

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

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

974 
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

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

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

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

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

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

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

981 

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

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

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

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

985 
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

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

987 

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

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

989 
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

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

991 

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

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

993 
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

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

995 

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

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

997 
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

998 

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

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

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

1001 

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

1002 
<li>Set <var>pipePromise</var> be a newlycreated <a>Promise</a></li> 
137  1003 

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

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

1005 

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

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

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

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

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

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

1011 

144  1012 
<li>Set <a>totalAmountTransferred</a> to 0</li> 
1013 

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

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

1015 

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

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

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

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

1019 

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

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

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

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

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

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

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

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

1027 

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

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

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

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

1031 
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

1032 
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

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

1034 

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

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

1036 
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

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

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

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

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

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

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

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

1044 

118  1045 
<dt>Promise&lt;undefined> readAbort(optional any reason)</dt> 
117  1046 
<dd> 
1047 
<p> 

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

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

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

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

1053 
Once this method has been called on a ReadableStream, no further method calls can be made on the ReadableStream. 
117  1054 
</p> 
1055 

1056 
<p> 

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

1057 
This method must run the steps below: 
117  1058 
<ol> 
147
be2de4c87594
More ReadableStream algorithm refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
146
diff
changeset

1059 
<li>Set <a>abortPromise</a> to a newlycreated <a>Promise</a></li> 
be2de4c87594
More ReadableStream algorithm refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
146
diff
changeset

1060 
<li>Send the <a>read abort</a> with <var>reason</var> to <a>dataSource</a> possibly asynchronously</li> 
be2de4c87594
More ReadableStream algorithm refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
146
diff
changeset

1061 
<li>Return <a>abortPromise</a></li> 
117  1062 
</ol> 
1063 
</p> 

1064 
</dd> 

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

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

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

1067 

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

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

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

1070 

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

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

1072 
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

1073 
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

1074 
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

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

1076 

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

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

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

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

1080 
<li> 
151  1081 
Produces data and delivers it to the associated <a>ReadableStream</a>. 
119
218f3b3a2df5
Add how to notify abort/error signal
Takeshi Yoshino <tyoshino@google.com>
parents:
118
diff
changeset

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

1083 
<li> 
147
be2de4c87594
More ReadableStream algorithm refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
146
diff
changeset

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

1085 
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

1086 
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

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

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

1089 
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

1090 
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

1091 
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

1092 
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

1093 
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

1094 
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

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

1096 
<li> 
147
be2de4c87594
More ReadableStream algorithm refactoring
Takeshi Yoshino <tyoshino@google.com>
parents:
146
diff
changeset

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

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

1103 
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

1104 
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

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

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

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

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

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

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

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

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

1113 

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

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

1115 
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

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

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

1118 

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

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

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

1121 

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

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

1123 
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

1124 
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

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

1126 

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

1127 
<p> 
139  1128 
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

1129 
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

1130 
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

1131 
A ReadableStream is registered with a data source on construction and 