Skip to content

Commit c7752f5

Browse files
committed
docs: add import in examples
So they can be copy-pasted and they work BREAKING CHANGE: First version of this package
1 parent 5f2f5fc commit c7752f5

File tree

1 file changed

+42
-9
lines changed

1 file changed

+42
-9
lines changed

README.md

+42-9
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ function sleep(time: number) {
6969
**This is a placeholder for any asynchronous task.**
7070

7171
> **Note:**
72-
> Avoid using this package on _"production"_ code.
72+
> _Avoid_ using this package on _"production"_ code.
7373
> Go [here](#when-to-use) to understand why.
7474
7575
### Mutex
@@ -112,6 +112,8 @@ However `myVar.i` is not protected, then the final value is `1`.
112112
If a mutex locks the task, then the variable is protected:
113113

114114
```typescript
115+
import { Mutex } from "@heap-code/concurrency-synchronization";
116+
115117
const mutex = new Mutex();
116118
const myVar = { i: 0 };
117119

@@ -150,6 +152,8 @@ It is possible to try to lock a mutex in a given time limit.
150152
The function will then throw an exception if the mutex could not lock in time:
151153

152154
```typescript
155+
import { ConcurrencyExceedTimeoutException } from "@heap-code/concurrency-synchronization";
156+
153157
mutex.tryLock(250).catch((error: unknown) => {
154158
if (error instanceof ConcurrencyExceedTimeoutException) {
155159
console.log("Could not lock in the given time.");
@@ -165,6 +169,8 @@ A mutex can be interrupted at any time.
165169
All awaiting _"threads"_ will then receive an exception:
166170

167171
```typescript
172+
import { ConcurrencyInterruptedException, Mutex } from "@heap-code/concurrency-synchronization";
173+
168174
const mutex = new Mutex();
169175
const myVar = { i: 0 };
170176

@@ -195,14 +201,16 @@ bootstrap();
195201

196202
### Semaphore
197203

198-
From [wikipedia](https://en.wikipedia.org/wiki/Semaphore_(programming)):
199-
204+
> From [wikipedia](https://en.wikipedia.org/wiki/Semaphore_(programming)):
205+
>
200206
> Semaphores are a type of synchronization primitive.
201207
202208
They can be used to protect certain resources (like mutexes),
203209
but are generally used for synchronization:
204210

205211
```typescript
212+
import { Semaphore } from "@heap-code/concurrency-synchronization";
213+
206214
async function bootstrap() {
207215
const semaphore = new Semaphore(0);
208216

@@ -230,6 +238,11 @@ It is possible to try to acquire a semaphore in a given time limit.
230238
The function will then throw an exception if the semaphore could not acquire in time:
231239

232240
```typescript
241+
import {
242+
ConcurrencyExceedTimeoutException,
243+
Semaphore
244+
} from "@heap-code/concurrency-synchronization";
245+
233246
async function bootstrap() {
234247
const semaphore = new Semaphore(2);
235248

@@ -254,6 +267,8 @@ A semaphore can be interrupted at any time.
254267
All awaiting _"threads"_ will then receive an exception:
255268

256269
```typescript
270+
import { ConcurrencyInterruptedException, Semaphore } from "@heap-code/concurrency-synchronization";
271+
257272
async function bootstrap() {
258273
const semaphore = new Semaphore(1);
259274

@@ -283,6 +298,8 @@ Very similar to [interrupt](#semaphore-interrupt),
283298
but it does not throw an exception.
284299

285300
```typescript
301+
import { Semaphore } from "@heap-code/concurrency-synchronization";
302+
286303
async function bootstrap() {
287304
const semaphore = new Semaphore(1);
288305

@@ -312,19 +329,21 @@ but it returns values on _acquire_.
312329
By default, all readings use an array:
313330

314331
```typescript
332+
import { ProducerConsumer } from "@heap-code/concurrency-synchronization";
333+
315334
async function bootstrap() {
316335
const producerConsumer = new ProducerConsumer([1]);
317336

318337
const time1 = 100;
319338
const time2 = 150;
320339

321-
sleep(time1).then(() => semaphore.write(3, 4));
322-
sleep(time2).then(() => semaphore.write(2));
340+
sleep(time1).then(() => producerConsumer.write(3, 4));
341+
sleep(time2).then(() => producerConsumer.write(2));
323342

324343
const maxTime = Math.max(time1, time2);
325344

326345
const before = performance.now();
327-
const valuesRead = await semaphore.read(4); // waiting until all is read
346+
const valuesRead = await producerConsumer.read(4); // waiting until all is read
328347
const after = performance.now();
329348

330349
const elapsed = after - before; // ~150
@@ -340,6 +359,11 @@ It is possible to try to read some values in a given time limit.
340359
The function will then throw an exception if it could not read in time:
341360

342361
```typescript
362+
import {
363+
ConcurrencyExceedTimeoutException,
364+
ProducerConsumer
365+
} from "@heap-code/concurrency-synchronization";
366+
343367
async function bootstrap() {
344368
const producerConsumer = new ProducerConsumer([1, 2, 3]);
345369

@@ -364,16 +388,18 @@ The `read` and `tryRead` have their "one"-method
364388
that do the same thing but return only one value instead of an array:
365389

366390
```typescript
391+
import { ProducerConsumer } from "@heap-code/concurrency-synchronization";
392+
367393
async function bootstrap() {
368394
const producerConsumer = new ProducerConsumer([1, 2]);
369395

370396
// const [value1] = producerConsumer.read(1);
371397
// can be written:
372-
const value1 = producerConsumer.readOne();
398+
const value1 = await producerConsumer.readOne();
373399

374400
// const [value2] = producerConsumer.tryRead(100, 1);
375401
// can be written:
376-
const value2 = producerConsumer.tryReadOne(100);
402+
const value2 = await producerConsumer.tryReadOne(100);
377403

378404
console.log(value1, value2); // 1 2
379405
}
@@ -386,14 +412,19 @@ A `ProducerConsumer` can be interrupted at any time.
386412
All awaiting _"threads"_ will then receive an exception:
387413

388414
```typescript
415+
import {
416+
ConcurrencyInterruptedException,
417+
ProducerConsumer
418+
} from "@heap-code/concurrency-synchronization";
419+
389420
async function bootstrap() {
390421
const producerConsumer = new ProducerConsumer([1]);
391422

392423
void sleep(100).then(() => producerConsumer.interrupt({ code: 502 }, [1, 2, 3]));
393424

394425
const succeed = await Promise.all([
395426
producerConsumer.read(3),
396-
producerConsumer.readOne(2),
427+
producerConsumer.readOne(),
397428
producerConsumer.tryRead(200, 3),
398429
producerConsumer.tryReadOne(200)
399430
]).catch((error: unknown) => {
@@ -421,6 +452,8 @@ if it comes from _regular_ observable or [subjects](https://rxjs.dev/guide/subje
421452
So this difference can be omitted with the following:
422453

423454
```typescript
455+
import { ProducerConsumer } from "@heap-code/concurrency-synchronization";
456+
424457
describe("My test", () => {
425458
it("should work", async () => {
426459
const producerConsumer = new ProducerConsumer();

0 commit comments

Comments
 (0)