Skip to content

Commit 29eee92

Browse files
author
Oren (electricessence)
committed
Improved docs.
1 parent 82095db commit 29eee92

20 files changed

+27069
-230
lines changed

‎docfx/.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
###############
2+
# folder #
3+
###############
4+
/**/DROP/
5+
/**/TEMP/
6+
/**/packages/
7+
/**/bin/
8+
/**/obj/
9+
_site

‎docfx/api/.manifest‎

Lines changed: 143 additions & 0 deletions
Large diffs are not rendered by default.

docfx/Open.ChannelExtensions.Extensions.yml renamed to docfx/api/Open.ChannelExtensions.Extensions.yml

File renamed without changes.

docfx/Open.ChannelExtensions.TransformChannel-2.yml renamed to docfx/api/Open.ChannelExtensions.TransformChannel-2.yml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,6 @@ items:
3535
description: Specifies the type of data that may be read from the channel.
3636
content.vb: >-
3737
Public Class TransformChannel(Of T, TResult)
38-
3938
Inherits TransformChannel(Of T, T, TResult)
4039
inheritance:
4140
- System.Object

‎docfx/api/Open.ChannelExtensions.TransformChannel-3.yml‎

Lines changed: 13486 additions & 0 deletions
Large diffs are not rendered by default.

docfx/Open.ChannelExtensions.yml renamed to docfx/api/Open.ChannelExtensions.yml

File renamed without changes.

‎docfx/api/toc.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
### YamlMime:TableOfContent
2+
- uid: Open.ChannelExtensions
3+
name: Open.ChannelExtensions
4+
items:
5+
- uid: Open.ChannelExtensions.Extensions
6+
name: Extensions
7+
- uid: Open.ChannelExtensions.TransformChannel`2
8+
name: TransformChannel<T, TResult>
9+
name.vb: TransformChannel(Of T, TResult)
10+
- uid: Open.ChannelExtensions.TransformChannel`3
11+
name: TransformChannel<TWrite, TRead, TResult>
12+
name.vb: TransformChannel(Of TWrite, TRead, TResult)

‎docfx/docfx.json‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,20 +9,26 @@
99
]
1010
}
1111
],
12-
"dest": ".",
12+
"dest": "api",
1313
"disableGitFeatures": false,
1414
"disableDefaultFilter": false,
15-
"properties": {
16-
"TargetFramework": "netstandard2.1"
15+
"properties":{
16+
"TargetFramework":"netstandard2.1"
1717
}
1818
}
1919
],
2020
"build": {
2121
"content": [
2222
{
2323
"files": [
24-
"**.yml",
25-
"index.md"
24+
"api/**.yml",
25+
"api/index.md"
26+
]
27+
},
28+
{
29+
"files": [
30+
"toc.yml",
31+
"*.md"
2632
]
2733
}
2834
],
@@ -35,8 +41,10 @@
3541
],
3642
"overwrite": [
3743
{
44+
"files": [
45+
"apidoc/**.md"
46+
],
3847
"exclude": [
39-
".editorconfig",
4048
"obj/**",
4149
"docs/**"
4250
]

‎docfx/index.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Open.ChannelExtensions
2+
3+
A set of extensions for optimizing/simplifying System.Threading.Channels usage.
4+
5+
## Highlights
6+
7+
Being able to define an asynchronous pipeline with best practice usage using simple expressive syntax:
8+
9+
```cs
10+
await Channel
11+
.CreateBounded<T>(10)
12+
.SourceAsync(source /* IEnumerable<Task<T>> */)
13+
.PipeAsync(
14+
maxConcurrency: 2,
15+
capacity: 5,
16+
transform: asyncTransform01)
17+
.Pipe(transform02, /* capacity */ 3)
18+
.ReadAllAsync(finalTransformedValue => {
19+
// Do something async with each final value.
20+
});
21+
```
22+
23+
```cs
24+
await source /* IEnumerable<T> */
25+
.ToChannel(boundedSize: 10, singleReader: true)
26+
.PipeAsync(asyncTransform01, /* capacity */ 5)
27+
.Pipe(
28+
maxConcurrency: 2,
29+
capacity: 3,
30+
transform: transform02)
31+
.ReadAll(finalTransformedValue => {
32+
// Do something with each final value.
33+
});
34+
```
35+
36+
## Examples
37+
38+
### Reading (until the channel is closed)
39+
40+
#### One by one read each entry from the channel
41+
42+
```cs
43+
await channel.ReadAll(
44+
entry => { /* Processing Code */ });
45+
```
46+
47+
```cs
48+
await channel.ReadAll(
49+
(entry, index) => { /* Processing Code */ });
50+
```
51+
52+
```cs
53+
await channel.ReadAllAsync(
54+
async entry => { await /* Processing Code */ });
55+
```
56+
57+
```cs
58+
await channel.ReadAllAsync(
59+
async (entry, index) => { await /* Processing Code */ });
60+
```
61+
62+
#### Read concurrently each entry from the channel
63+
64+
```cs
65+
await channel.ReadAllConcurrently(
66+
maxConcurrency,
67+
entry => { /* Processing Code */ });
68+
```
69+
70+
```cs
71+
await channel.ReadAllConcurrentlyAsync(
72+
maxConcurrency,
73+
async entry => { await /* Processing Code */ });
74+
```
75+
76+
### Writing
77+
78+
If `complete` is `true`, the channel will be closed when the source is empty.
79+
80+
#### Dump a source enumeration into the channel
81+
82+
```cs
83+
// source can be any IEnumerable<T>.
84+
await channel.WriteAll(source, complete: true);
85+
```
86+
87+
```cs
88+
// source can be any IEnumerable<Task<T>> or IEnumerable<ValueTask<T>>.
89+
await channel.WriteAllAsync(source, complete: true);
90+
```
91+
92+
#### Synchronize reading from the source and process the results concurrently
93+
94+
```cs
95+
// source can be any IEnumerable<Task<T>> or IEnumerable<ValueTask<T>>.
96+
await channel.WriteAllConcurrentlyAsync(
97+
maxConcurrency, source, complete: true);
98+
```
99+
100+
### Pipelining / Transforming
101+
102+
#### Transform and buffer entries
103+
104+
```cs
105+
// Transform values in a source channel to new unbounded channel.
106+
var transformed = channel.Pipe(
107+
async value => /* transformation */);
108+
```
109+
110+
```cs
111+
// Transform values in a source channel to new unbounded channel with a max concurrency of X.
112+
const X = 4;
113+
var transformed = channel.Pipe(
114+
X, async value => /* transformation */);
115+
```
116+
117+
```cs
118+
// Transform values in a source channel to new bounded channel bound of N entries.
119+
const N = 5;
120+
var transformed = channel.Pipe(
121+
async value => /* transformation */, N);
122+
```
123+
124+
```cs
125+
// Transform values in a source channel to new bounded channel bound of N entries with a max concurrency of X.
126+
const X = 4;
127+
const N = 5;
128+
var transformed = channel.Pipe(
129+
X, async value => /* transformation */, N);
130+
131+
// or
132+
transformed = channel.Pipe(
133+
maxConcurrency: X,
134+
capacity: N,
135+
transform: async value => /* transformation */);
136+
```

‎docfx/toc.yml‎

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,3 @@
1-
### YamlMime:TableOfContent
2-
- uid: Open.ChannelExtensions
3-
name: Open.ChannelExtensions
4-
items:
5-
- uid: Open.ChannelExtensions.Extensions
6-
name: Extensions
7-
- uid: Open.ChannelExtensions.TransformChannel`2
8-
name: TransformChannel<T, TResult>
9-
name.vb: TransformChannel(Of T, TResult)
10-
- uid: Open.ChannelExtensions.TransformChannel`3
11-
name: TransformChannel<TWrite, TRead, TResult>
12-
name.vb: TransformChannel(Of TWrite, TRead, TResult)
1+
- name: Open.ChannelExtensions
2+
href: api/Open.ChannelExtensions.Extensions.html
3+
homepage: api/Open.ChannelExtensions.html

0 commit comments

Comments
 (0)