author  Takeshi Yoshino <tyoshino@google.com> 
Tue, 10 Dec 2013 01:20:10 +0900  
changeset 118  360cd31579a7 
parent 117  6ccb7d75a511 
child 119  218f3b3a2df5 
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> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

123 
This includes: 
0
af7713ef49dc
Adding Editors Draft
eliotgra@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> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

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

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

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

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

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

135 
<li> 
99
b3b8bbde934f
Teminology: Tuple > struct type
Takeshi Yoshino <tyoshino@google.com>
parents:
98
diff
changeset

136 
A struct type named <a>ByteStreamReadResult</a> which represents the result of consuming operations such as <code>read()</code> and <code>pipe()</code>. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

137 
It holds a chunk of content read from a <a>ReadableByteStream</a>, the number of bytes consumed, and EOF signal. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

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

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

143 
A list of notable byte stream <a href="#producers">producers</a> and <a href="#consumers">consumers</a> for which we can apply either or both of <a>ReadableByteStream</a> and <a>WritableByteStream</a> model. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

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

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

149 
Extensions to <a href="http://dev.w3.org/2006/webapi/FileAPI/#dfncreateObjectURL">URL.createObjectURL</a> and 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

150 
<a href="http://dev.w3.org/2006/webapi/FileAPI/#dfnrevokeObjectURL">URL.revokeObjectURL</a> to add support for <a>ReadableByteStream</a>. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

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

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

153 

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

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

155 
This API is designed to be used in conjunction with other APIs and elements on the web platform, notably: 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

156 
<a href="http://dev.w3.org/2006/webapi/FileAPI">File</a> [[!FILEAPI]], 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

157 
<a href="http://dev.w3.org/2006/webapi/XMLHttpRequest2">XMLHttpRequest</a> 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

158 
(e.g. with an overloaded <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest2/#thesendmethod"><code>send()</code></a> method 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

159 
and <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest2/#theresponsetypeattribute"><code>response</code></a> object for <a>ReadableByteStream</a> objects) [[!XMLHTTPREQUEST2]], 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

160 
<a href="http://dev.w3.org/html5/postmsg/#domwindowpostmessage"><code>postMessage</code></a>, and 
8
cb4e62ad9587
Switching to respec version
fmoussa <feras.moussa@hotmail.com>
parents:
7
diff
changeset

161 
Web Workers [[!WEBWORKERS]]. 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

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

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

164 

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

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

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

167 

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

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

169 
Web applications should have the ability to acquire, manipulate, and pass data in a wide variety of forms, including as a sequence of data made available over time. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

170 
This specification defines the basic representation for byte streams, and programmatic ways to read and write streams of data and errors raised on those operations. 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

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

172 

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

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

174 
The <a>WritableByteStream</a> interface defines a general protocol for <a href="#consumers">data consuming APIs</a> to communicate with data producing code. 
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

175 
In these cases, the data consuming API, such as a decoder, provides a <a>WritableByteStream</a> for other applications to write to, enabling the decoder to begin decoding data as it becomes available. 
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

176 
The data is written to the internal data sink of a data consuming API using: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

178 
<li>The <code>write()</code> method for writing bytes to the data sink as a <a>ArrayBufferView</a>, <a>DOMString</a> or <a>Blob</a></li> 
87
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

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

180 
The <code>awaitSpaceAvailable()</code> method for allowing a dataproducer to write to the data sink only when the data sink specifies it is now available to consume more data. 
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

181 
This is useful for cases where an app may want to avoid backpressure and filling the internal buffer. 
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

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

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

184 
Actual transfer of bytes to the data sink may happen either synchronously or asynchronously. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

185 
<a>WritableByteStream</a> hides the details of actual communication with the data sink while allowing for an efficient transfer of bytes. 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

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

187 

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

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

189 
The <a>ReadableByteStream</a> interface defines a general protocol for <a href="#producers">data producing APIs</a> to communicate with data consuming code. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

190 
This interface represents the potential for an infinite amount of bytes which are obtained over time and read once. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

191 
Data consuming code reads data from the data source inside a data producing API using: 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

193 
<li>The <code>read()</code> and <code>readExact()</code> methods for reading bytes from the data source as a <a>ArrayBufferView</a>, <a>DOMString</a> or <a>Blob</a></li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

194 
<li>The <code>pullAmount</code> attribute to pace data retrieval from the data source</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

195 
<li>The <code>pipe()</code> method for transferring data in bulk from the data source into the data sink of a <a>WritableByteStream</a> from another API</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

197 
Actual transfer of bytes from the data source may happen either synchronously or asynchronously. 
87
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

198 
The <a>ReadableByteStream</a> hides the details of actual communication with the data source while allowing for an efficient transfer of bytes. 
24
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

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

200 

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

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

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

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

204 
<li>Delayed notification of completion by using <a>Promise</a>s</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

205 
<li>Explicit back pressure management by propagating room for consumption back to producers</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

206 
<li><a>WritableByteStream</a> always accepts incoming data synchronously</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

209 

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

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

211 
The <a>ByteStream</a> is a simple implementation of both the <a>WritableByteStream</a> and <a>ReadableByteStream</a> interface. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

212 
A ByteStream has a single queue of bytes and it works as a data sink for the WritableByteStream interface and as a data source for the ReadableByteStream interface. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

214 

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

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

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

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

218 
Error conditions that may arise during an operation will be handled by the reject callback set to the Promise. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

221 

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

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

223 
In the example below, different code blocks handle progress, error, and success conditions. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

224 
The example demonstrates how to read a chunk of data from a <a>ReadableByteStream</a> using <code>read()</code>. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

225 
The <a>ReadableByteStream</a> may of come from a <a href="#producers">producer</a> such as <code>XMLHttpRequest</code>. 
77  226 
Additionally, it demonstrates how to read bytes from a <a>ReadableByteStream</a> until an EOF is encountered. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

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

228 

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

231 
stream.pullAmount = 1024; 

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

232 
stream.readEncoding = "UTF8"; 
01eb488cd8c4
Complete update of streams spec to support promises and further refinements
fmoussa <feras.moussa@hotmail.com>
parents:
23
diff
changeset

233 
stream.readType = "arraybuffer"; 
77  234 
stream.read().then( 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

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

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

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

241 

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

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

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

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

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

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

247 

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

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

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

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

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

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

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

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

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

256 

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

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

258 

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

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

260 
In the example below, different code blocks handle progress, error, and success conditions. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

261 
The example below demonstrates how to obtain a <a>ReadableByteStream</a> from <a>XMLHttpRequest</a> to begin playing a large video in <code>readystate</code> LOADING. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

262 
The example takes the <a>ReadableByteStream</a> from a <a href="#producers">producer</a>, <a>XMLHttpRequest</a>, and gives it to a <a href="#consumers">consumer</a>, the video tag. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

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

264 

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

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

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

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

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

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

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

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

272 

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

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

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

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

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

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

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

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

280 

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

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

282 
In addition to the <a>ReadableByteStream</a> interface, this specification introduces an interface called <a>WritableByteStream</a> for data consuming APIs. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

283 
The <a>WritableByteStream</a> interface provides a <code>write()</code> method which allows applications to write data to a <a href="#consumers">data consuming API</a>. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

284 
<code>write()</code> supports writing bytes represented as a <a>Blob</a>, <a>ArrayBuffer</a>, or <a>DOMString</a>. 
0
af7713ef49dc
Adding Editors Draft
eliotgra@ELIOTGRAX220.redmond.corp.microsoft.com
parents:
diff
changeset

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

286 
<p> 
77  287 
The example below demonstrates how to use <code>write()</code> to load a <a>ReadableByteStream</a> into the audio tag, whose data could be processed and built dynamically at read time. 
288 
ByteStream in the example is a class which implements both <a>WritableByteStream</a> and <a>ReadableByteStream</a>. 

289 
It accepts bytes generated by the code via <a>WritableByteStream</a> methods, and the written data will be consumed by the audio element via the object URL which is a part of <a>ReadableByteStream</a>'s functionality. 

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

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

291 

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

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

293 

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

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

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

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

297 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

313 

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

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

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

316 

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

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

318 

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

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

320 
A producer can also do work only when pulled by using <code>awaitSpaceAvailable()</code>, which will inform the producer when to produce data. 
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

321 
This is useful when 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

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

323 

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

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

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

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

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

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

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

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

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

332 

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

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

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

335 

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

336 
<section class="section" id="writableByteStream"> 
81  337 
<h2>WritableByteStream Interface</h2> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

339 
The WritableByteStream interface defines a protocol for APIs which consume byte streams. 
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

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

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

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

343 
<li>How to notify the writer of completion of writing</li> 
77  344 
<li>How to notify the writer of how much data can be accepted currently</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

346 

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

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

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

349 

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

350 
<p> 
88
ef2c58cd8563
Rephrased dataSink definition
Takeshi Yoshino <tyoshino@google.com>
parents:
87
diff
changeset

351 
The actual data consumer behind the WritableByteStream is called a data sink and is identified by <dfn>dataSink</dfn>. 
ef2c58cd8563
Rephrased dataSink definition
Takeshi Yoshino <tyoshino@google.com>
parents:
87
diff
changeset

352 
A data sink consumes byte streams and notifies the WritableByteStream of the number of bytes the data sink can newly accept. 
109
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

353 
For each data sink, it's defined how to calculate <a>cost</a> of each object which the data sink can consume. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

355 

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

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

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

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

359 

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

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

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

362 

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

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

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

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

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

367 
Specifies a <a>DOMString</a> that represents the label of an encoding [[!EncodingDetermination]]. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

368 
If set, it will be used as part of the encoding determination used when processing a <a>DOMString</a> provided in a <code>write()</code> method call. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

369 
It will return the label last set, or the empty DOMString if never set. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

371 

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

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

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

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

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

376 

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

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

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

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

380 
This method writes the specified <var>data</var> to the WritableByteStream. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

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

382 

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

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

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

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

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

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

388 

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

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

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

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

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

393 

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

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

395 

115  396 
<li>If <var>cost</var> argument is specified, let <var>amountToWrite</var> be <var>cost</var> argument. Otherwise, let <var>amountToWrite</var> be the <a>cost</a> of <var>data</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

397 

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

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

399 

98
3b89f8cea0fd
More tuple > pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents:
97
diff
changeset

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

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

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

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

404 

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

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

406 

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

407 
<li>Return <var>writePromise</var>, and then continue to process the steps in this algorithm</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

408 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

424 

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

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

426 
If <var>data</var> argument is an <a>ArrayBufferView</a>, modifications made on the ArrayBufferView's contents between <code>write()</code> method call and fulfill of the returned Promise may affect the data written to <a>dataSink</a>. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

428 

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

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

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

431 
<dd>Data to write.</dd> 
115  432 
<dt>optional [Clamp] unsigned long long cost</dt> 
433 
<dd>Overrides <a>cost</a> of data.</dd> 

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

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

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

436 

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

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

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

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

440 
This method waits until the WritableByteStream becomes able to accept any nonzero amount of data. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

441 
The returned <a>Promise</a> will be fulfilled with the number of bytes the WritableByteStream can accept. 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

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

443 

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

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

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

446 
<ol> 
110
6a7a40bde1e5
Abort wait > abort waiting
Takeshi Yoshino <tyoshino@google.com>
parents:
109
diff
changeset

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

448 

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

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

450 
<li>Return <a>waitPromise</a>, and then continue to process the steps in this algorithm</li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

451 
<li>Wait until <a>pendingWriteQueue</a> is empty and <a>spaceAvailable</a> is not 0</li> 
37
0de575d7b79a
 Unify indentation to tabs.
Takeshi Yoshino <tyoshino@google.com>
parents:
35
diff
changeset

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

453 
Queue a task to run the steps below: 
38
3cdd8b2d21d9
Merging changes made for preparing WD
Takeshi Yoshino <tyoshino@google.com>
parents:
37
diff
changeset

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

455 
<li>If <a>waitPromise</a> is <code>null</code>, terminate these steps</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

458 
<li>Fulfill <var>detachedWaitPromise</var> with <a>spaceAvailable</a></li> 
38
3cdd8b2d21d9
Merging changes made for preparing WD
Takeshi Yoshino <tyoshino@google.com>
parents:
37
diff
changeset

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

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

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

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

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

464 

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

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

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

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

468 
This method tells the WritableByteStream that no more data will be written to it. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

471 

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

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

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

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

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

476 
<li>Return <var>closePromise</var>, and then continue the process the steps in this algorithm</li> 
56c80502bb30
Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
102
diff
changeset

477 
<li>Write the EOF to <a>dataSink</a></li> 
56c80502bb30
Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
102
diff
changeset

478 
<li>Wait until <a>dataSink</a> acknowledges the EOF</li> 
56c80502bb30
Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
102
diff
changeset

479 
<li>Fulfill <var>closePromise</var> with <code>undefined</code></li> 
56c80502bb30
Change writeClose() return type to Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
102
diff
changeset

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

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

482 
</dd> 
116  483 

118  484 
<dt>Promise&lt;undefined> writeAbort(optional any reason)</dt> 
116  485 
<dd> 
486 
<p> 

487 
This method tells the WritableByteStream that no more data will be written to it with indication of error. 

488 
The details of the error will be given by <var>reason</var> argument. 

489 
The interpretation of <var>reason</var> is up to <a>dataSink</a>. 

490 
Once writeAbort() has been called on a WritableByteStream, no further method calls can be made on the WritableByteStream. 

491 
</p> 

492 

493 
<p> 

494 
This method must run the steps below: 

495 
<ol> 

496 
<li>Let <var>abortPromise</var> be a new <a>Promise</a></li> 

497 
<li>Return <var>abortPromise</var>, and then continue the process the steps in this algorithm</li> 

498 
<li><a>Writeabort</a> <a>dataSink</a> with <var>reason</var></li> 

499 
<li>Wait until <a>dataSink</a> acknowledges the writeabort</li> 

500 
<li>Fulfill <var>abortPromise</var> with <code>undefined</code></li> 

501 
</ol> 

502 
</p> 

503 
</dd> 

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

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

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

506 

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

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

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

509 

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

510 
<p> 
79
548c5e39ff07
Renaming variables and one grammar fix
Takeshi Yoshino <tyoshino@google.com>
parents:
78
diff
changeset

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

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

513 

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

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

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

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

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

518 
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

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

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

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

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

523 
<li> 
116  524 
Accepts the writeabort signal with an object parameter named reason. 
525 
</li> 

526 
<li> 

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

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

528 
When and how to generate such notifications is up to data sinks. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

531 
<li> 
116  532 
Notifies <a>WritableByteStream</a> of acknowledgement of the EOF signal. 
533 
</li> 

534 
<li> 

535 
Notifies <a>WritableByteStream</a> of acknowledgement of the writeabort signal. 

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

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

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

538 
How to calculate an integer value <dfn>cost</dfn> of each object which the data sink can consume. 
44cada6acb2f
Make write() agnostic to data type
Takeshi Yoshino <tyoshino@google.com>
parents:
108
diff
changeset

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

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

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

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

543 

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

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

545 
<h2>Interacting with the data sink</h2> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

546 

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

547 
<p> 
93
33fa9ecdbe74
A bit tweak on data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents:
92
diff
changeset

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

549 
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

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

551 

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

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

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

554 
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

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

556 

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

557 
<p> 
86
d1e43b22a73d
Complement waitPromise definition sentence
Takeshi Yoshino <tyoshino@google.com>
parents:
85
diff
changeset

558 
A WritableByteStream has an associated <a>Promise</a> <dfn>waitPromise</dfn> which is used by the <code>awaitSpaceAvailable()</code> method. 
93
33fa9ecdbe74
A bit tweak on data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents:
92
diff
changeset

559 
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

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

561 

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

562 
<p> 
110
6a7a40bde1e5
Abort wait > abort waiting
Takeshi Yoshino <tyoshino@google.com>
parents:
109
diff
changeset

563 
To <dfn>abort waiting</dfn>, run the steps below: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

565 
<li>If <a>waitPromise</a> is <code>null</code>, terminate these steps</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

569 
</ol> 
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> 
94
e06bf08768db
Formatting data sink definition
Takeshi Yoshino <tyoshino@google.com>
parents:
93
diff
changeset

573 
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

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

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

576 
<li>An integer <var>amount</var></li> 
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

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

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

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

580 

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

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

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

583 
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

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

585 

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

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

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

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

589 
<li>If <a>pendingWriteQueue</a> is empty, break from this loop</li> 
91
3ed9f08a1f23
Renames for readability
Takeshi Yoshino <tyoshino@google.com>
parents:
90
diff
changeset

590 
<li>Let <var>pendingWrite</var> be the head element of <a>pendingWriteQueue</a></li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

591 
<li>Let <var>amountToAcknowledge</var> be min(<var>pendingWrite.amount</var>  <var>pendingWrite.ackedAmount</var>, <a>spaceAvailable</a>)</li> 
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

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

593 
<li>Set <var>pendingWrite.ackedAmount</var> to <var>pendingWrite.ackedAmount</var> + <var>amountToAcknowledge</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

595 
If <var>pendingWrite.ackedAmount</var> equals to <var>pendingWrite.amount</var>, run the steps below: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

597 
<li>Pop <var>pendingWrite</var> from <a>pendingWriteQueue</a></li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

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

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

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

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

602 

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

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

604 
When <a>dataSink</a> requests <var>amountNewlyRequested</var> more data, queue a task which runs the steps below: 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

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

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

610 
</section> 
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="readableByteStream"> 
89  614 
<h2>ReadableByteStream Interface</h2> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

616 
The ReadableByteStream interface defines a protocol for APIs which produce a byte stream. This protocol includes: 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

618 
<li>How to receive a read request from the reader and output bytes</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

622 

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

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

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> 
77  627 
Interfaces introduced in this section provide simple and convenient ways to consume data. 
628 
They connect arbitrary byte stream producer and byte stream consuming JavaScript code using Promises and method invocations. 

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

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> 
87
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

632 
A ReadableByteStream has a onetoone mapping with an associated data source, and has defined semantics for <a href='#interactingWithDataSource'>interacting with the data source internally</a>. 
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

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

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

635 

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

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

638 

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

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

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

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

642 
Returns the ASCIIencoded string in lower case representing the media type of the <code>Stream</code>, 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

643 
expressed as an RFC2046 MIME type [[!RFC2046]]. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

644 
Conforming user agents SHOULD return the MIME type of the <code>ReadableByteStream</code>, if it is known. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

645 
If conforming user agents cannot determine the media type of the <code>ReadableByteStream</code>, they MUST return the empty string. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

646 
A string is a valid MIME type if it matches the mediatype token defined in section 3.7 "Media Types" of RFC 2616 [[!HTTP11]]. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

648 

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

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

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

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

652 
Specifies what data type will be returned by a <code>read()</code> and <code>readExact()</code> method call. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

653 
This attribute can be set to any of the supported types in <a>ByteStreamReadType</a>. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

654 
The default value for this attribute is "<code>arraybuffer</code>". 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

657 

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

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

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

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

661 
Specifies a <a>DOMString</a> that represents the label of an encoding [[!EncodingDetermination]]. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

662 
If set, it will be used as part of the encoding determination used when processing a <code>read()</code> method call. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

664 

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

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

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

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

668 
</dd> 
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 
<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

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

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

673 
This attribute provides ReadableByteStream with a hint of how much data the reader can consume currently. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

676 

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

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

678 
When this attribute is set, <a>retrieve data</a>. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

680 

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

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

682 
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

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

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

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

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

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

688 

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

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

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

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

692 
This method reads data from the ReadableByteStream. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

693 
The returned Promise is fulfilled only when bytes of the specified size is read or the EOF is reached. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

694 
The size of data read by this method is exactly the same as the specified size unless an EOF was reached, in which case there will be less bytes, which were the remaining bytes until the EOF. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

696 

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

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

698 
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

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

700 
<li>If <a href="#widlReadableByteStreamreadType">readType</a> is "<code>text</code>" throw a "<code><a>SyntaxError</a></code>"</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

701 

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

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

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

704 

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

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

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

707 

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

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

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

710 

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

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

712 

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

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

714 
<li>Return <var>readPromise</var>, and then continue to process the steps in this algorithm</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

715 

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

716 
<li>Wait until the number of bytes in <a>readDataBuffer</a> becomes equal to or greater than <var>size</var> or <a>eofReached</a> is set</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

717 

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

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

719 
Queue a task which runs the steps below: 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

721 
<li>Let <var>readableAmount</var> be the number of bytes in <a>readDataBuffer</a></li> 
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

722 
<li>Let <var>amountToReturn</var> be min(<var>size</var>, <var>readableAmount</var>)</li> 
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

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

724 
<li>Pop <var>amountToReturn</var> bytes from <a>readDataBuffer</a>, and then let <var>readBytes</var> be the popped bytes</li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

725 

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

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

727 

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

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

729 

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

730 
<li>Let <var>result</var> be a new <a>ByteStreamReadResult</a></li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

733 
<dt>If <var>latchedType</var> is "<code>none</code>"</dt> 
108
2cd69f4494a8
More "foo of bar" > "bar.foo"
Takeshi Yoshino <tyoshino@google.com>
parents:
107
diff
changeset

734 
<dd>Set <var>result</var>.<a href="#widlByteStreamReadResultdata">data</a> to <code>undefined</code></dd> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

735 
<dt>Otherwise</dt> 
108
2cd69f4494a8
More "foo of bar" > "bar.foo"
Takeshi Yoshino <tyoshino@google.com>
parents:
107
diff
changeset

736 
<dd>Set <var>result</var>.<a href="#widlByteStreamReadResultdata">data</a> to an object of the type specified by <var>latchedType</var> which represents <var>readBytes</var></dd> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

739 
<li>Set <a href="#widlByteStreamReadResulteof">eof</a> of <var>result</var> to <code>true</code> if <a>readDataBuffer</a> is empty and <a>eofReached</a> is set</li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

740 
<li>Set <a href="#widlByteStreamReadResultamountConsumed">amountConsumed</a> of <var>result</var> to <var>amountToReturn</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

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

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

746 

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

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

748 
<dt>[Clamp] unsigned long long size</dt> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

751 

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

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

753 
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

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

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

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

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

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

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

760 

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

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

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

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

764 
This method reads data from the ReadableByteStream. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

765 
The speed of reading can be roughly adjusted by using <a href="#widlByteStreamReadResultpullAmount">pullAmount</a>. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

768 

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

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

770 
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

771 

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

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

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

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

775 

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

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

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

778 

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

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

780 

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

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

782 

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

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

784 
<li>Return <var>readPromise</var>, and then continue to process the steps in this algorithm</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

785 

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

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

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

788 
<dt>If <var>latchedType</var> is "<code>text</code>"</dt> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

792 
Wait until bytes in <a>readDataBuffer</a> can be converted into a nonempty <a>DOMString</a> when decoded using <var>latchedEncoding</var> or <a>eofReached</a> is set 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

795 
Queue a task which runs the rest of this algorithm 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

798 
Pop nonzero number of bytes from <a>readDataBuffer</a> which can be fully converted into a nonempty <a>DOMString</a> when decoded using <var>latchedEncoding</var>, and then let <var>readBytes</var> be the result of the conversion. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

799 
If <a>eofReached</a> is set and there are no such bytes, reject <var>readPromise</var> and terminate these steps. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

802 
Let <var>readData</var> be the result of decoding <var>readBytes</var> using <var>latchedEncoding</var>. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

803 
If this throws an <var>exception</var>, reject <var>readPromise</var> with <var>exception</var>. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

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

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

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

810 
<li>Wait until <a>readDataBuffer</a> becomes nonempty or <a>eofReached</a> is set</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

812 
Queue a task which runs the rest of this algorithm 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

815 
Pop nonzero number of bytes from <a>readDataBuffer</a>, and then let <var>readBytes</var> be the popped bytes 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

817 
Implementations may choose to pop only part of bytes readable if it helps reducing memory copy. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

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

822 
<dt>If <var>latchedType</var> is "<code>none</code>"</dt> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

823 
<dd>Let <var>readData</var> be <code>undefined</code></dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

825 
<dd>Let <var>readData</var> be an object of the type specified by <var>latchedType</var> which represents <var>readBytes</var></dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

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

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

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

832 
<li>Let <var>amountConsumed</var> be the size of <var>readBytes</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

833 

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

834 
<li>Let <var>result</var> be a new <a>ByteStreamReadResult</a>.</li> 
106
4b349a87fc7c
More foo of bar > bar.foo clean up
Takeshi Yoshino <tyoshino@google.com>
parents:
105
diff
changeset

835 
<li>Set <var>result</var>.<a href="#widlByteStreamReadResultdata">data</a> to <var>readData</var></li> 
4b349a87fc7c
More foo of bar > bar.foo clean up
Takeshi Yoshino <tyoshino@google.com>
parents:
105
diff
changeset

836 
<li>Set <var>result</var>.<a href="#widlByteStreamReadResulteof">eof</a> to <code>true</code> if <a>eofReached</a> is set and <a>readDataBuffer</a> is empty</li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

837 
<li>Set <var>result</var>.<a href="#widlByteStreamReadResultamountConsumed">amountConsumed</a> to <var>amountConsumed</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

838 

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

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

840 

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

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

842 

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

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

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

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

846 

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

848 
<img src="images/fulfilling.png" alt="How new data is automatically fetched"> 
78  849 
</p> 
850 

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

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

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

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

854 
<li>You don't 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

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

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

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

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

859 

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

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

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

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

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

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

865 

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

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

867 
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

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

869 

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

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

871 
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

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

873 

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

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

875 
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

876 

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

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

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

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

880 

110
6a7a40bde1e5
Abort wait > abort waiting
Takeshi Yoshino <tyoshino@google.com>
parents:
109
diff
changeset

881 
<li>Run <a>abort waiting</a> algorithm on <var>destination</var></a> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

882 

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

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

884 

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

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

886 

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

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

888 
<li>Return <var>pipePromise</var>, and then continue to process the steps in this algorithm</li> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

889 

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

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

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

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

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

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

895 
Whenever <a>readDataBuffer</a> is not empty or <a>eofReached</a> is set, 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

897 
<dt>If this happened in the event loop</dt> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

900 
<dd>Queue a task which runs the steps below</dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

904 
Let <var>readableAmount</var> be the number of bytes in <a>readDataBuffer</a> 
100
7421b9a22a7e
More bug fix in pipe(). numBytesRequested is used where numBytesSpaceAvailable must be used.
Takeshi Yoshino <tyoshino@google.com>
parents:
99
diff
changeset

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

906 
It's fine to process only part of the bytes, and process the rest in the next task. 
7421b9a22a7e
More bug fix in pipe(). numBytesRequested is used where numBytesSpaceAvailable must be used.
Takeshi Yoshino <tyoshino@google.com>
parents:
99
diff
changeset

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

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

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

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

911 
<dt>If <var>size</var> is specified</dt> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

912 
<dd>Let <var>amountToTransfer</var> be min(<var>size</var>  <var>totalAmountTransferred</var>, <var>readableAmount</var>)</dd> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

914 
<dd>Let <var>amountToTransfer</var> be <var>readableAmount</var></dd> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

917 
<li>Set <a>amountBeingReturned</a> to <a>amountBeingReturned</a> + <var>amountToTransfer</var></li> 
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

918 
<li>Pop <var>amountToTransfer</var> bytes from <a>readDataBuffer</a>, and then write it to <a>dataSink</a> of <var>destination</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

919 

98
3b89f8cea0fd
More tuple > pendingWrite renaming
Takeshi Yoshino <tyoshino@google.com>
parents:
97
diff
changeset

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

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

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

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

924 

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

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

926 

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

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

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

929 
<dt>If <a>eofReached</a> is set</dt> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

930 
<dd>Break from this loop</dd> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

931 
<dt>If <var>size</var> is specified and <var>totalAmountTransferred</var> equals to <var>size</var></dt> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

935 
Need to revisit. Finish when write to the destination completes? 
a176607d4c3a
TODO about pipe() finish timing
Takeshi Yoshino <tyoshino@google.com>
parents:
101
diff
changeset

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

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

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

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

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

941 
Whenever <a>pendingWriteQueue</a> of <var>destination</var> is empty and <a>spaceAvailable</a> of <var>destination</var> is not 0, 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

943 
<dt>If this happened in the event loop</dt> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

946 
<dd>Queue a task which runs the steps below</dd> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

949 
<li>Let <var>destSpaceAvailable</var> be <a>spaceAvailable</a> of <var>destination</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

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

954 
Set <a>pipePullAmount</a> to min(<var>size</var>  <var>totalAmountTransferred</var>, <var>destSpaceAvailable</var>) 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

957 
I.e. only bytes of the same number as the number of bytes writable to <var>destination</var> are retrieved from the data source. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

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

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

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

964 
<dd>Set <a>pipePullAmount</a> to <var>destSpaceAvailable</var></dd> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

967 
<li>Set <a>amountBeingReturned</a> to 0</li> 
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

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

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

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

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

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

973 

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

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

975 

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

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

977 

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

978 
<li>Let <var>result</var> be a new <a>ByteStreamReadResult</a></li> 
105
0ba39ba3955b
Fix typo in pipe() algorithm
Takeshi Yoshino <tyoshino@google.com>
parents:
104
diff
changeset

979 
<li>Set <var>result</var>.<a href="#widlByteStreamReadResultdata">data</a> to <code>undefined</code>. 
101
7da4a886ff9f
More pipe() bug fixes
Takeshi Yoshino <tyoshino@google.com>
parents:
100
diff
changeset

980 
<li>Set <var>result</var>.<a href="#widlByteStreamReadResulteof">eof</a> to <code>true</code> if <a>eofReached</a></li> 
107
276491848949
Rename variables agnostic to type of data Streams API handles
Takeshi Yoshino <tyoshino@google.com>
parents:
106
diff
changeset

981 
<li>Set <var>result</var>.<a href="#widlByteStreamReadResultamountConsumed">amountConsumed</a> to <var>totalAmountTransferred</var></li> 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

985 
At this point, <a>amountBeingReturned</a> is not yet reset 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

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

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

990 

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

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

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

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

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

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

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

997 
</dd> 
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 
<dt>ReadableByteStream fork()</dt> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

1002 
This method creates a new ReadableByteStream which refers to the same <a>dataSource</a> as the current ReadableByteStream. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

1005 

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

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

1007 
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

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

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

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

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

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

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

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

1015 

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

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

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

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

1019 
This method tells the ReadableByteStream that no more data will be read from it without indication of any error. 
69234a5f02a6
Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
103
diff
changeset

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

1021 

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

1022 
<p> 
69234a5f02a6
Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
103
diff
changeset

1023 
This method must run the steps below: 
69234a5f02a6
Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
103
diff
changeset

1024 
<ol> 
69234a5f02a6
Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
103
diff
changeset

1025 
<li>Let <var>closePromise</var> be a new <a>Promise</a></li> 
69234a5f02a6
Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
103
diff
changeset

1026 
<li>Return <var>closePromise</var>, and then continue the process the steps in this algorithm</li> 
69234a5f02a6
Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
103
diff
changeset

1027 
<li>Notify <a>dataSource</a> of readClosure</li> 
69234a5f02a6
Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
103
diff
changeset

1028 
<li>Wait until <a>dataSource</a> acknowledges the readClosure</li> 
69234a5f02a6
Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
103
diff
changeset

1029 
<li>Fulfill <var>closePromise</var> with <code>undefined</code></li> 
69234a5f02a6
Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
103
diff
changeset

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

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

1032 
</dd> 
117  1033 

118  1034 
<dt>Promise&lt;undefined> readAbort(optional any reason)</dt> 
117  1035 
<dd> 
1036 
<p> 

1037 
This method tells the ReadableByteStream that no more data will be read from it with indication of error. 

1038 
The details of the error will be given by <var>reason</var> argument. 

1039 
The interpretation of <var>reason</var> is up to <a>dataSource</a>. 

1040 
Once readAbort() has been called on a ReadableByteStream, no further method calls can be made on the ReadableByteStream. 

1041 
</p> 

1042 

1043 
<p> 

1044 
This method must run the steps below: 

1045 
<ol> 

1046 
<li>Let <var>abortPromise</var> be a new <a>Promise</a></li> 

1047 
<li>Return <var>abortPromise</var>, and then continue the process the steps in this algorithm</li> 

1048 
<li><a>Readabort</a> <a>dataSource</a> with <var>reason</var></li> 

1049 
<li>Wait until <a>dataSource</a> acknowledges the readabort</li> 

1050 
<li>Fulfill <var>abortPromise</var> with <code>undefined</code></li> 

1051 
</ol> 

1052 
</p> 

1053 
</dd> 

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

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

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

1056 

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

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

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

1059 

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

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

1061 
A data source produces the bytes to be consumed via the <a>ReadableByteStream</a> interface instances. 
95
af7f31ca4da3
Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents:
94
diff
changeset

1062 
A <a>ReadableByteStream</a> retrieves bytes from an associated data source. 
87
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

1063 
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="#widlReadableByteStreamforkReadableByteStream">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

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

1065 

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

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

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

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

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

1070 
Produces bytes. Newly produced bytes will be delivered to the associated <a>ReadableByteStream</a>. 
af7f31ca4da3
Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents:
94
diff
changeset

1071 
</li> 
af7f31ca4da3
Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents:
94
diff
changeset

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

1073 
Accepts requests for production of bytes from a <a>ReadableByteStream</a>. A byte production request consists of an integer indicating the number of bytes to produce in addition to already requested ones. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1074 
Interpretation of the request is up to data sources. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1075 
Data sources may respond to retrieval requests with data larger than requested. 
95
af7f31ca4da3
Data source rephrasing and clarification
Takeshi Yoshino <tyoshino@google.com>
parents:
94
diff
changeset

1076 
Requests and delivery of bytes don't need to 1to1 correspond. 
76
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1077 
Data sources may produce bytes and send to <a>ReadableByteStream</a> unsolicitedly without receiving any retrieval request. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

1080 
Accepts and acknowledges readClosure signal which means the associated <a>ReadableByteStream</a> has completed consuming bytes from this data source without indication of any error. 
69234a5f02a6
Change readClose to return a Promise
Takeshi Yoshino <tyoshino@google.com>
parents:
103
diff
changeset

1081 
</li> 
117  1082 
<li> 
1083 
Accepts and acknowledges readabort signal which means the associated <a>ReadableByteStream</a> has completed consuming bytes from this data source with indication of any error. 

1084 
</li> 

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

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

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

1087 

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

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

1089 
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

1090 
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

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

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

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

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

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

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

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

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

1099 

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

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

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

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

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

1104 

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

1105 
<section class="section" id="interactingWithDataSource"> 
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

1106 
<h2>Interacting with the data source</h2> 
dcf26e7c77fe
Break at the end of each sentence.
Takeshi Yoshino <tyoshino@google.com>
parents:
86
diff
changeset

1107 

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

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

1109 
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

1110 
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

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

1112 

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

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

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

1115 
The data source model is explained in <a href="#h2_data_source">this section</a>. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1116 
A data source can be shared by multiple ReadableByteStream instances when <code>fork()</code> is used. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

1117 
A ReadableByteStream is registered with a data source on construction and given a reader ID. 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail.com>
parents:
46
diff
changeset

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

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

1120 

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

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

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

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

1124 

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

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

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

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

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

1129 

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

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

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

1132 
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

1133 
</p> 
63f6521d7457
Moved preview to overview, and added note about preview deprication
fmoussa <feras.moussa@hotmail 