reactphp.github.io/event-loop/index.html at master · reactphp/reactphp.github.io

History

1323 lines (1253 loc) · 126 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

675

676

677

678

679

680

681

682

683

684

685

686

687

688

689

690

691

692

693

694

695

696

697

698

699

700

701

702

703

704

705

706

707

708

709

710

711

712

713

714

715

716

717

718

719

720

721

722

723

724

725

726

727

728

729

730

731

732

733

734

735

736

737

738

739

740

741

742

743

744

745

746

747

748

749

750

751

752

753

754

755

756

757

758

759

760

761

762

763

764

765

766

767

768

769

770

771

772

773

774

775

776

777

778

779

780

781

782

783

784

785

786

787

788

789

790

791

792

793

794

795

796

797

798

799

800

801

802

803

804

805

806

807

808

809

810

811

812

813

814

815

816

817

818

819

820

821

822

823

824

825

826

827

828

829

830

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

847

848

849

850

851

852

853

854

855

856

857

858

859

860

861

862

863

864

865

866

867

868

869

870

871

872

873

874

875

876

877

878

879

880

881

882

883

884

885

886

887

888

889

890

891

892

893

894

895

896

897

898

899

900

901

902

903

904

905

906

907

908

909

910

911

912

913

914

915

916

917

918

919

920

921

922

923

924

925

926

927

928

929

930

931

932

933

934

935

936

937

938

939

940

941

942

943

944

945

946

947

948

949

950

951

952

953

954

955

956

957

958

959

960

961

962

963

964

965

966

967

968

969

970

971

972

973

974

975

976

977

978

979

980

981

982

983

984

985

986

987

988

989

990

991

992

993

994

995

996

997

998

999

1000

<!DOCTYPE html>

<head>

<title>EventLoop - ReactPHP</title>

</head>

<body>

</a>

</form>

Menu

</div>

</button>

</div>

</button>

</section>

<a class="off-canvas-menu__section-top" href="../changelog.html">Changelog</a>

</section>

<h3 class="off-canvas-menu__section-header">Core Components</h3>

<li>

EventLoop

v1.6.0

</a>

</li>

<li>

Stream

v1.4.0

</a>

</li>

<li>

Promise

v3.3.0

</a>

</li>

<li>

Async

v4.3.0

</a>

</li>

</ul>

</section>

<h3 class="off-canvas-menu__section-header">Network Components</h3>

<li>

Socket

v1.17.0

</a>

</li>

<li>

Datagram

v1.10.0

</a>

</li>

<li>

HTTP

v1.11.0

</a>

</li>

<li>

DNS

v1.14.0

</a>

</li>

</ul>

</section>

<h3 class="off-canvas-menu__section-header">Utility Components</h3>

<li>

Cache

v1.2.0

</a>

</li>

<li>

ChildProcess

v0.6.7

</a>

</li>

<li>

PromiseTimer

v1.11.0

</a>

</li>

<li>

PromiseStream

v1.7.0

</a>

</li>

</ul>

</section>

<h3 class="off-canvas-menu__section-header">Legacy Components</h3>

<li>

HttpClient

v0.5.11

</a>

</li>

<li>

SocketClient

v0.7.0

</a>

</li>

</ul>

</section>

</div>

</nav>

</div>

</header>

<h1>EventLoop</h1>

<div class="markdown-heading"><h1 class="heading-element">EventLoop</h1><a id="eventloop" class="anchor" aria-label="Permalink: EventLoop" href="#eventloop"></a></div>

<a href="https://reactphp.org/" rel="nofollow">ReactPHP</a>'s core reactor event loop that libraries can use for evented I/O.

In order for async based libraries to be interoperable, they need to use the

same event loop. This component provides a common <code>LoopInterface</code> that any

library can target. This allows them to be used in the same loop, with one

single <a href="#run"><code>run()</code></a> call that is controlled by the user.

Table of contents

<ul>

<li><a href="#quickstart-example">Quickstart example</a></li>

<li>

<a href="#usage">Usage</a>

<ul>

<li>

<ul>

<li><a href="#loop-methods">Loop methods</a></li>

<li><a href="#loop-autorun">Loop autorun</a></li>

</ul>

</li>

<li>

<a href="#factory"><del>Factory</del></a>

<ul>

<li><a href="#create"><del>create()</del></a></li>

</ul>

</li>

<li>

<a href="#loop-implementations">Loop implementations</a>

<ul>

<li><a href="#streamselectloop">StreamSelectLoop</a></li>

<li><a href="#exteventloop">ExtEventLoop</a></li>

<li><a href="#extevloop">ExtEvLoop</a></li>

<li><a href="#extuvloop">ExtUvLoop</a></li>

<li><a href="#extlibeventloop"><del>ExtLibeventLoop</del></a></li>

<li><a href="#extlibevloop"><del>ExtLibevLoop</del></a></li>

</ul>

</li>

<li>

<a href="#loopinterface">LoopInterface</a>

<ul>

<li><a href="#addtimer">addTimer()</a></li>

<li><a href="#addperiodictimer">addPeriodicTimer()</a></li>

<li><a href="#canceltimer">cancelTimer()</a></li>

<li><a href="#futuretick">futureTick()</a></li>

<li><a href="#addsignal">addSignal()</a></li>

<li><a href="#removesignal">removeSignal()</a></li>

<li><a href="#addreadstream">addReadStream()</a></li>

<li><a href="#addwritestream">addWriteStream()</a></li>

<li><a href="#removereadstream">removeReadStream()</a></li>

<li><a href="#removewritestream">removeWriteStream()</a></li>

</ul>

</li>

</ul>

</li>

<li><a href="#install">Install</a></li>

<li><a href="#tests">Tests</a></li>

<li><a href="#license">License</a></li>

</ul>

<div class="markdown-heading"><h2 class="heading-element">Quickstart example</h2><a id="quickstart-example" class="anchor" aria-label="Permalink: Quickstart example" href="#quickstart-example"></a></div>

Here is an async HTTP server built with just the event loop.

<div class="highlight highlight-text-html-php"><pre><?php

use React\EventLoop\Loop;

require __DIR__ . '/vendor/autoload.php';

$server = stream_socket_server('tcp://127.0.0.1:8080');

stream_set_blocking($server, false);

Loop::addReadStream($server, function ($server) {

$conn = stream_socket_accept($server);

$data = "HTTP/1.1 200 OK\r\nContent-Length: 3\r\n\r\nHi\n";

Loop::addWriteStream($conn, function ($conn) use (&$data) {

$written = fwrite($conn, $data);

if ($written === strlen($data)) {

fclose($conn);

Loop::removeWriteStream($conn);

} else {

$data = substr($data, $written);

}

});

Loop::addPeriodicTimer(5, function () {

$memory = memory_get_usage() / 1024;

$formatted = number_format($memory, 3).'K';

echo "Current memory usage: {$formatted}\n";

});</pre></div>

See also the <a href="https://github.com/reactphp/event-loop/blob/v1.6.0/examples">examples</a>.

<div class="markdown-heading"><h2 class="heading-element">Usage</h2><a id="usage" class="anchor" aria-label="Permalink: Usage" href="#usage"></a></div>

Typical applications would use the <a href="#loop"><code>Loop</code> class</a> to use the default

event loop like this:

<div class="highlight highlight-text-html-php"><pre>use React\EventLoop\Loop;

$timer = Loop::addPeriodicTimer(0.1, function () {

echo 'Tick' . PHP_EOL;

});

Loop::addTimer(1.0, function () use ($timer) {

Loop::cancelTimer($timer);

echo 'Done' . PHP_EOL;

});</pre></div>

As an alternative, you can also explicitly create an event loop instance at the

beginning, reuse it throughout your program and finally run it at the end of the

program like this:

<div class="highlight highlight-text-html-php"><pre>$loop = React\EventLoop\Loop::get(); // or deprecated React\EventLoop\Factory::create();

$timer = $loop->addPeriodicTimer(0.1, function () {

echo 'Tick' . PHP_EOL;

});

$loop->addTimer(1.0, function () use ($loop, $timer) {

$loop->cancelTimer($timer);

echo 'Done' . PHP_EOL;

});

$loop->run();</pre></div>

While the former is more concise, the latter is more explicit.

In both cases, the program would perform the exact same steps.

<ol>

<li>The event loop instance is created at the beginning of the program. This is

implicitly done the first time you call the <a href="#loop"><code>Loop</code> class</a> or

explicitly when using the deprecated <a href="#create"><code>Factory::create()</code> method</a>

(or manually instantiating any of the <a href="#loop-implementations">loop implementations</a>).</li>

<li>The event loop is used directly or passed as an instance to library and

application code. In this example, a periodic timer is registered with the

event loop which simply outputs <code>Tick</code> every fraction of a second until another

timer stops the periodic timer after a second.</li>

<li>The event loop is run at the end of the program. This is automatically done

when using the <a href="#loop"><code>Loop</code> class</a> or explicitly with a single <a href="#run"><code>run()</code></a>

call at the end of the program.</li>

</ol>

As of <code>v1.2.0</code>, we highly recommend using the <a href="#loop"><code>Loop</code> class</a>.

The explicit loop instructions are still valid and may still be useful in some

applications, especially for a transition period towards the more concise style.

The <code>Loop</code> class exists as a convenient global accessor for the event loop.

<div class="markdown-heading"><h4 class="heading-element">Loop methods</h4><a id="loop-methods" class="anchor" aria-label="Permalink: Loop methods" href="#loop-methods"></a></div>

The <code>Loop</code> class provides all methods that exist on the <a href="#loopinterface"><code>LoopInterface</code></a>

as static methods:

<ul>

<li><a href="#addtimer">addTimer()</a></li>

<li><a href="#addperiodictimer">addPeriodicTimer()</a></li>

<li><a href="#canceltimer">cancelTimer()</a></li>

<li><a href="#futuretick">futureTick()</a></li>

<li><a href="#addsignal">addSignal()</a></li>

<li><a href="#removesignal">removeSignal()</a></li>

<li><a href="#addreadstream">addReadStream()</a></li>

<li><a href="#addwritestream">addWriteStream()</a></li>

<li><a href="#removereadstream">removeReadStream()</a></li>

<li><a href="#removewritestream">removeWriteStream()</a></li>

</ul>

If you're working with the event loop in your application code, it's often

easiest to directly interface with the static methods defined on the <code>Loop</code> class

like this:

<div class="highlight highlight-text-html-php"><pre>use React\EventLoop\Loop;

$timer = Loop::addPeriodicTimer(0.1, function () {

echo 'Tick' . PHP_EOL;

});

Loop::cancelTimer($timer);

echo 'Done' . PHP_EOL;

});</pre></div>

On the other hand, if you're familiar with object-oriented programming (OOP) and

dependency injection (DI), you may want to inject an event loop instance and

invoke instance methods on the <code>LoopInterface</code> like this:

<div class="highlight highlight-text-html-php"><pre>use React\EventLoop\Loop;

use React\EventLoop\LoopInterface;

class Greeter

{

private $loop;

public function __construct(LoopInterface $loop)

{

$this->loop = $loop;

}

public function greet(string $name)

{

$this->loop->addTimer(1.0, function () use ($name) {

echo 'Hello ' . $name . '!' . PHP_EOL;

});

}

$greeter = new Greeter(Loop::get());

$greeter->greet('Alice');

$greeter->greet('Bob');</pre></div>

Each static method call will be forwarded as-is to the underlying event loop

instance by using the <a href="#get"><code>Loop::get()</code></a> call internally.

See <a href="#loopinterface"><code>LoopInterface</code></a> for more details about available methods.

<div class="markdown-heading"><h4 class="heading-element">Loop autorun</h4><a id="loop-autorun" class="anchor" aria-label="Permalink: Loop autorun" href="#loop-autorun"></a></div>

When using the <code>Loop</code> class, it will automatically execute the loop at the end of

the program. This means the following example will schedule a timer and will

automatically execute the program until the timer event fires:

<div class="highlight highlight-text-html-php"><pre>use React\EventLoop\Loop;

Loop::addTimer(1.0, function () {

echo 'Hello' . PHP_EOL;

});</pre></div>

As of <code>v1.2.0</code>, we highly recommend using the <code>Loop</code> class this way and omitting any

explicit <a href="#run"><code>run()</code></a> calls. For BC reasons, the explicit <a href="#run"><code>run()</code></a>

method is still valid and may still be useful in some applications, especially

for a transition period towards the more concise style.

If you don't want the <code>Loop</code> to run automatically, you can either explicitly

<a href="#run"><code>run()</code></a> or <a href="#stop"><code>stop()</code></a> it. This can be useful if you're using

a global exception handler like this:

<div class="highlight highlight-text-html-php"><pre>use React\EventLoop\Loop;

Loop::addTimer(10.0, function () {

echo 'Never happens';

});

set_exception_handler(function (Throwable $e) {

echo 'Error: ' . $e->getMessage() . PHP_EOL;

Loop::stop();

});

throw new RuntimeException('Demo');</pre></div>

The <code>get(): LoopInterface</code> method can be used to

get the currently active event loop instance.

This method will always return the same event loop instance throughout the

lifetime of your application.

<div class="highlight highlight-text-html-php"><pre>use React\EventLoop\Loop;

use React\EventLoop\LoopInterface;

$loop = Loop::get();

assert($loop instanceof LoopInterface);

assert($loop === Loop::get());</pre></div>

This is particularly useful if you're using object-oriented programming (OOP)

and dependency injection (DI). In this case, you may want to inject an event

loop instance and invoke instance methods on the <code>LoopInterface</code> like this:

<div class="highlight highlight-text-html-php"><pre>use React\EventLoop\Loop;

use React\EventLoop\LoopInterface;

class Greeter

{

private $loop;

{

$this->loop = $loop;

}

public function greet(string $name)

{

});

}

$greeter = new Greeter(Loop::get());

$greeter->greet('Alice');

$greeter->greet('Bob');</pre></div>

See <a href="#loopinterface"><code>LoopInterface</code></a> for more details about available methods.

<div class="markdown-heading"><h3 class="heading-element"><del>Factory</del></h3><a id="factory" class="anchor" aria-label="Permalink: Factory" href="#factory"></a></div>

Deprecated since v1.2.0, see <a href="#loop"><code>Loop</code> class</a> instead.

</blockquote>

The deprecated <code>Factory</code> class exists as a convenient way to pick the best available

<a href="#loop-implementations">event loop implementation</a>.

<div class="markdown-heading"><h4 class="heading-element"><del>create()</del></h4><a id="create" class="anchor" aria-label="Permalink: create()" href="#create"></a></div>

Deprecated since v1.2.0, see <a href="#get"><code>Loop::get()</code></a> instead.

</blockquote>

The deprecated <code>create(): LoopInterface</code> method can be used to

create a new event loop instance:

<div class="highlight highlight-text-html-php"><pre>// deprecated

$loop = React\EventLoop\Factory::create();

// new

$loop = React\EventLoop\Loop::get();</pre></div>

This method always returns an instance implementing <a href="#loopinterface"><code>LoopInterface</code></a>,

the actual <a href="#loop-implementations">event loop implementation</a> is an implementation detail.

This method should usually only be called once at the beginning of the program.

<div class="markdown-heading"><h3 class="heading-element">Loop implementations</h3><a id="loop-implementations" class="anchor" aria-label="Permalink: Loop implementations" href="#loop-implementations"></a></div>

In addition to the <a href="#loopinterface"><code>LoopInterface</code></a>, there are a number of

event loop implementations provided.

All of the event loops support these features:

<ul>

<li>File descriptor polling</li>

<li>One-off timers</li>

<li>Periodic timers</li>

<li>Deferred execution on future loop tick</li>

</ul>

For most consumers of this package, the underlying event loop implementation is

an implementation detail.

You should use the <a href="#loop"><code>Loop</code> class</a> to automatically create a new instance.

Advanced! If you explicitly need a certain event loop implementation, you can

manually instantiate one of the following classes.

Note that you may have to install the required PHP extensions for the respective

event loop implementation first or they will throw a <code>BadMethodCallException</code> on creation.

<div class="markdown-heading"><h4 class="heading-element">StreamSelectLoop</h4><a id="streamselectloop" class="anchor" aria-label="Permalink: StreamSelectLoop" href="#streamselectloop"></a></div>

A <code>stream_select()</code> based event loop.

This uses the <a href="https://www.php.net/manual/en/function.stream-select.php" rel="nofollow"><code>stream_select()</code></a>

function and is the only implementation that works out of the box with PHP.

This event loop works out of the box on PHP 5.3 through PHP 8+ and HHVM.

This means that no installation is required and this library works on all

platforms and supported PHP versions.

Accordingly, the <a href="#loop"><code>Loop</code> class</a> and the deprecated <a href="#factory"><code>Factory</code></a>

will use this event loop by default if you do not install any of the event loop

extensions listed below.

Under the hood, it does a simple <code>select</code> system call.

This system call is limited to the maximum file descriptor number of

<code>FD_SETSIZE</code> (platform dependent, commonly 1024) and scales with <code>O(m)</code>

(<code>m</code> being the maximum file descriptor number passed).

This means that you may run into issues when handling thousands of streams

concurrently and you may want to look into using one of the alternative

event loop implementations listed below in this case.

If your use case is among the many common use cases that involve handling only

dozens or a few hundred streams at once, then this event loop implementation

performs really well.

If you want to use signal handling (see also <a href="#addsignal"><code>addSignal()</code></a> below),

this event loop implementation requires <code>ext-pcntl</code>.

This extension is only available for Unix-like platforms and does not support

Windows.

It is commonly installed as part of many PHP distributions.

If this extension is missing (or you're running on Windows), signal handling is

not supported and throws a <code>BadMethodCallException</code> instead.

This event loop is known to rely on wall-clock time to schedule future timers

when using any version before PHP 7.3, because a monotonic time source is

only available as of PHP 7.3 (<code>hrtime()</code>).

While this does not affect many common use cases, this is an important

distinction for programs that rely on a high time precision or on systems

that are subject to discontinuous time adjustments (time jumps).

This means that if you schedule a timer to trigger in 30s on PHP < 7.3 and

then adjust your system time forward by 20s, the timer may trigger in 10s.

See also <a href="#addtimer"><code>addTimer()</code></a> for more details.

<div class="markdown-heading"><h4 class="heading-element">ExtEventLoop</h4><a id="exteventloop" class="anchor" aria-label="Permalink: ExtEventLoop" href="#exteventloop"></a></div>

An <code>ext-event</code> based event loop.

This uses the <a href="https://pecl.php.net/package/event" rel="nofollow"><code>event</code> PECL extension</a>,

that provides an interface to <code>libevent</code> library.

<code>libevent</code> itself supports a number of system-specific backends (epoll, kqueue).

This loop is known to work with PHP 5.4 through PHP 8+.

<div class="markdown-heading"><h4 class="heading-element">ExtEvLoop</h4><a id="extevloop" class="anchor" aria-label="Permalink: ExtEvLoop" href="#extevloop"></a></div>

An <code>ext-ev</code> based event loop.

This loop uses the <a href="https://pecl.php.net/package/ev" rel="nofollow"><code>ev</code> PECL extension</a>,

that provides an interface to <code>libev</code> library.

<code>libev</code> itself supports a number of system-specific backends (epoll, kqueue).

This loop is known to work with PHP 5.4 through PHP 8+.

<div class="markdown-heading"><h4 class="heading-element">ExtUvLoop</h4><a id="extuvloop" class="anchor" aria-label="Permalink: ExtUvLoop" href="#extuvloop"></a></div>

An <code>ext-uv</code> based event loop.

This loop uses the <a href="https://pecl.php.net/package/uv" rel="nofollow"><code>uv</code> PECL extension</a>,

that provides an interface to <code>libuv</code> library.

<code>libuv</code> itself supports a number of system-specific backends (epoll, kqueue).

This loop is known to work with PHP 7+.

<div class="markdown-heading"><h4 class="heading-element"><del>ExtLibeventLoop</del></h4><a id="extlibeventloop" class="anchor" aria-label="Permalink: ExtLibeventLoop" href="#extlibeventloop"></a></div>

Deprecated since v1.2.0, use <a href="#exteventloop"><code>ExtEventLoop</code></a> instead.

</blockquote>

An <code>ext-libevent</code> based event loop.

This uses the <a href="https://pecl.php.net/package/libevent" rel="nofollow"><code>libevent</code> PECL extension</a>,

that provides an interface to <code>libevent</code> library.

<code>libevent</code> itself supports a number of system-specific backends (epoll, kqueue).

This event loop does only work with PHP 5.

An <a href="https://github.com/php/pecl-event-libevent/pull/2">unofficial update</a> for

PHP 7 does exist, but it is known to cause regular crashes due to <code>SEGFAULT</code>s.

To reiterate: Using this event loop on PHP 7 is not recommended.

Accordingly, neither the <a href="#loop"><code>Loop</code> class</a> nor the deprecated

<a href="#factory"><code>Factory</code> class</a> will try to use this event loop on PHP 7.

This event loop is known to trigger a readable listener only if

the stream becomes readable (edge-triggered) and may not trigger if the

stream has already been readable from the beginning.

This also implies that a stream may not be recognized as readable when data

is still left in PHP's internal stream buffers.

As such, it's recommended to use <code>stream_set_read_buffer($stream, 0);</code>

to disable PHP's internal read buffer in this case.

See also <a href="#addreadstream"><code>addReadStream()</code></a> for more details.

<div class="markdown-heading"><h4 class="heading-element"><del>ExtLibevLoop</del></h4><a id="extlibevloop" class="anchor" aria-label="Permalink: ExtLibevLoop" href="#extlibevloop"></a></div>

Deprecated since v1.2.0, use <a href="#extevloop"><code>ExtEvLoop</code></a> instead.

</blockquote>

An <code>ext-libev</code> based event loop.

This uses an <a href="https://github.com/m4rw3r/php-libev">unofficial <code>libev</code> extension</a>,

that provides an interface to <code>libev</code> library.

<code>libev</code> itself supports a number of system-specific backends (epoll, kqueue).

This loop does only work with PHP 5.

An update for PHP 7 is <a href="https://github.com/m4rw3r/php-libev/issues/8">unlikely</a>

to happen any time soon.

<div class="markdown-heading"><h3 class="heading-element">LoopInterface</h3><a id="loopinterface" class="anchor" aria-label="Permalink: LoopInterface" href="#loopinterface"></a></div>

The <code>run(): void</code> method can be used to

run the event loop until there are no more tasks to perform.

For many applications, this method is the only directly visible

invocation on the event loop.

As a rule of thumb, it is usually recommended to attach everything to the

same loop instance and then run the loop once at the bottom end of the

application.

This method will keep the loop running until there are no more tasks

to perform. In other words: This method will block until the last

timer, stream and/or signal has been removed.

Likewise, it is imperative to ensure the application actually invokes

this method once. Adding listeners to the loop and missing to actually

run it will result in the application exiting without actually waiting

for any of the attached listeners.

This method MUST NOT be called while the loop is already running.

This method MAY be called more than once after it has explicitly been

<a href="#stop"><code>stop()</code>ped</a> or after it automatically stopped because it

previously did no longer have anything to do.

The <code>stop(): void</code> method can be used to

instruct a running event loop to stop.

This method is considered advanced usage and should be used with care.

As a rule of thumb, it is usually recommended to let the loop stop

only automatically when it no longer has anything to do.

This method can be used to explicitly instruct the event loop to stop:

<div class="highlight highlight-text-html-php"><pre>$loop->addTimer(3.0, function () use ($loop) {

$loop->stop();

});</pre></div>

Calling this method on a loop instance that is not currently running or

on a loop instance that has already been stopped has no effect.

<div class="markdown-heading"><h4 class="heading-element">addTimer()</h4><a id="addtimer" class="anchor" aria-label="Permalink: addTimer()" href="#addtimer"></a></div>

The <code>addTimer(float $interval, callable $callback): TimerInterface</code> method can be used to

enqueue a callback to be invoked once after the given interval.

The second parameter MUST be a timer callback function that accepts

the timer instance as its only parameter.

If you don't use the timer instance inside your timer callback function

you MAY use a function which has no parameters at all.

The timer callback function MUST NOT throw an <code>Exception</code>.

The return value of the timer callback function will be ignored and has

no effect, so for performance reasons you're recommended to not return

any excessive data structures.

This method returns a timer instance. The same timer instance will also be

passed into the timer callback function as described above.

You can invoke <a href="#canceltimer"><code>cancelTimer</code></a> to cancel a pending timer.

Unlike <a href="#addperiodictimer"><code>addPeriodicTimer()</code></a>, this method will ensure

the callback will be invoked only once after the given interval.

<div class="highlight highlight-text-html-php"><pre>$loop->addTimer(0.8, function () {

echo 'world!' . PHP_EOL;

});

$loop->addTimer(0.3, function () {

echo 'hello ';

});</pre></div>

See also <a href="https://github.com/reactphp/event-loop/blob/v1.6.0/examples">example #1</a>.

If you want to access any variables within your callback function, you

can bind arbitrary data to a callback closure like this:

<div class="highlight highlight-text-html-php"><pre>function hello($name, LoopInterface $loop)

{

echo "hello $name\n";

});

}

hello('Tester', $loop);</pre></div>

This interface does not enforce any particular timer resolution, so

special care may have to be taken if you rely on very high precision with

millisecond accuracy or below. Event loop implementations SHOULD work on

a best effort basis and SHOULD provide at least millisecond accuracy

unless otherwise noted. Many existing event loop implementations are

known to provide microsecond accuracy, but it's generally not recommended

to rely on this high precision.

Similarly, the execution order of timers scheduled to execute at the

same time (within its possible accuracy) is not guaranteed.

This interface suggests that event loop implementations SHOULD use a

monotonic time source if available. Given that a monotonic time source is

only available as of PHP 7.3 by default, event loop implementations MAY

fall back to using wall-clock time.

While this does not affect many common use cases, this is an important

distinction for programs that rely on a high time precision or on systems

that are subject to discontinuous time adjustments (time jumps).

This means that if you schedule a timer to trigger in 30s and then adjust

your system time forward by 20s, the timer SHOULD still trigger in 30s.

See also <a href="#loop-implementations">event loop implementations</a> for more details.

<div class="markdown-heading"><h4 class="heading-element">addPeriodicTimer()</h4><a id="addperiodictimer" class="anchor" aria-label="Permalink: addPeriodicTimer()" href="#addperiodictimer"></a></div>

The <code>addPeriodicTimer(float $interval, callable $callback): TimerInterface</code> method can be used to

enqueue a callback to be invoked repeatedly after the given interval.

The second parameter MUST be a timer callback function that accepts

the timer instance as its only parameter.

If you don't use the timer instance inside your timer callback function

you MAY use a function which has no parameters at all.

The timer callback function MUST NOT throw an <code>Exception</code>.

The return value of the timer callback function will be ignored and has

no effect, so for performance reasons you're recommended to not return

any excessive data structures.

This method returns a timer instance. The same timer instance will also be

passed into the timer callback function as described above.

Unlike <a href="#addtimer"><code>addTimer()</code></a>, this method will ensure the callback

will be invoked infinitely after the given interval or until you invoke

<a href="#canceltimer"><code>cancelTimer</code></a>.

<div class="highlight highlight-text-html-php"><pre>$timer = $loop->addPeriodicTimer(0.1, function () {

echo 'tick!' . PHP_EOL;

});

$loop->cancelTimer($timer);

echo 'Done' . PHP_EOL;

});</pre></div>

See also <a href="https://github.com/reactphp/event-loop/blob/v1.6.0/examples">example #2</a>.

If you want to limit the number of executions, you can bind

arbitrary data to a callback closure like this:

{

$n = 3;

$loop->addPeriodicTimer(1.0, function ($timer) use ($name, $loop, &$n) {

if ($n > 0) {

--$n;

echo "hello $name\n";

} else {

$loop->cancelTimer($timer);

}

});

}

hello('Tester', $loop);</pre></div>

This interface does not enforce any particular timer resolution, so

special care may have to be taken if you rely on very high precision with

millisecond accuracy or below. Event loop implementations SHOULD work on

a best effort basis and SHOULD provide at least millisecond accuracy

unless otherwise noted. Many existing event loop implementations are

known to provide microsecond accuracy, but it's generally not recommended

to rely on this high precision.

Similarly, the execution order of timers scheduled to execute at the

same time (within its possible accuracy) is not guaranteed.

This interface suggests that event loop implementations SHOULD use a

monotonic time source if available. Given that a monotonic time source is

only available as of PHP 7.3 by default, event loop implementations MAY

fall back to using wall-clock time.

While this does not affect many common use cases, this is an important

distinction for programs that rely on a high time precision or on systems

that are subject to discontinuous time adjustments (time jumps).

This means that if you schedule a timer to trigger in 30s and then adjust

your system time forward by 20s, the timer SHOULD still trigger in 30s.

See also <a href="#loop-implementations">event loop implementations</a> for more details.

Additionally, periodic timers may be subject to timer drift due to

re-scheduling after each invocation. As such, it's generally not

recommended to rely on this for high precision intervals with millisecond

accuracy or below.

<div class="markdown-heading"><h4 class="heading-element">cancelTimer()</h4><a id="canceltimer" class="anchor" aria-label="Permalink: cancelTimer()" href="#canceltimer"></a></div>

The <code>cancelTimer(TimerInterface $timer): void</code> method can be used to

cancel a pending timer.

See also <a href="#addperiodictimer"><code>addPeriodicTimer()</code></a> and <a href="https://github.com/reactphp/event-loop/blob/v1.6.0/examples">example #2</a>.

Calling this method on a timer instance that has not been added to this

loop instance or on a timer that has already been cancelled has no effect.

<div class="markdown-heading"><h4 class="heading-element">futureTick()</h4><a id="futuretick" class="anchor" aria-label="Permalink: futureTick()" href="#futuretick"></a></div>

The <code>futureTick(callable $listener): void</code> method can be used to

schedule a callback to be invoked on a future tick of the event loop.

This works very much similar to timers with an interval of zero seconds,

but does not require the overhead of scheduling a timer queue.

The tick callback function MUST be able to accept zero parameters.

The tick callback function MUST NOT throw an <code>Exception</code>.

The return value of the tick callback function will be ignored and has

no effect, so for performance reasons you're recommended to not return

any excessive data structures.

If you want to access any variables within your callback function, you

can bind arbitrary data to a callback closure like this:

{

$loop->futureTick(function () use ($name) {

echo "hello $name\n";

});

}

hello('Tester', $loop);</pre></div>

Unlike timers, tick callbacks are guaranteed to be executed in the order

they are enqueued.

Also, once a callback is enqueued, there's no way to cancel this operation.

This is often used to break down bigger tasks into smaller steps (a form

of cooperative multitasking).

<div class="highlight highlight-text-html-php"><pre>$loop->futureTick(function () {

echo 'b';

});

$loop->futureTick(function () {

echo 'c';

});

echo 'a';</pre></div>

See also <a href="https://github.com/reactphp/event-loop/blob/v1.6.0/examples">example #3</a>.

<div class="markdown-heading"><h4 class="heading-element">addSignal()</h4><a id="addsignal" class="anchor" aria-label="Permalink: addSignal()" href="#addsignal"></a></div>

The <code>addSignal(int $signal, callable $listener): void</code> method can be used to

This is useful to catch user interrupt signals or shutdown signals from

tools like <code>supervisor</code> or <code>systemd</code>.

The second parameter MUST be a listener callback function that accepts

the signal as its only parameter.

If you don't use the signal inside your listener callback function

you MAY use a function which has no parameters at all.

The listener callback function MUST NOT throw an <code>Exception</code>.

The return value of the listener callback function will be ignored and has

no effect, so for performance reasons you're recommended to not return

any excessive data structures.

<div class="highlight highlight-text-html-php"><pre>$loop->addSignal(SIGINT, function (int $signal) {

echo 'Caught user interrupt signal' . PHP_EOL;

});</pre></div>

See also <a href="https://github.com/reactphp/event-loop/blob/v1.6.0/examples">example #4</a>.

Signaling is only available on Unix-like platforms, Windows isn't

supported due to operating system limitations.

This method may throw a <code>BadMethodCallException</code> if signals aren't

supported on this platform, for example when required extensions are

missing.

Note: A listener can only be added once to the same signal, any

attempts to add it more than once will be ignored.

<div class="markdown-heading"><h4 class="heading-element">removeSignal()</h4><a id="removesignal" class="anchor" aria-label="Permalink: removeSignal()" href="#removesignal"></a></div>

The <code>removeSignal(int $signal, callable $listener): void</code> method can be used to

remove a previously added signal listener.

<div class="highlight highlight-text-html-php"><pre>$loop->removeSignal(SIGINT, $listener);</pre></div>

Any attempts to remove listeners that aren't registered will be ignored.

<div class="markdown-heading"><h4 class="heading-element">addReadStream()</h4><a id="addreadstream" class="anchor" aria-label="Permalink: addReadStream()" href="#addreadstream"></a></div>

Advanced! Note that this low-level API is considered advanced usage.

Most use cases should probably use the higher-level

<a href="../stream/#readablestreaminterface">readable Stream API</a>

instead.

</blockquote>

The <code>addReadStream(resource $stream, callable $callback): void</code> method can be used to

The first parameter MUST be a valid stream resource that supports

checking whether it is ready to read by this loop implementation.

A single stream resource MUST NOT be added more than once.

Instead, either call <a href="#removereadstream"><code>removeReadStream()</code></a> first or

react to this event with a single listener and then dispatch from this

listener. This method MAY throw an <code>Exception</code> if the given resource type

is not supported by this loop implementation.

The second parameter MUST be a listener callback function that accepts

the stream resource as its only parameter.

If you don't use the stream resource inside your listener callback function

you MAY use a function which has no parameters at all.

The listener callback function MUST NOT throw an <code>Exception</code>.

The return value of the listener callback function will be ignored and has

no effect, so for performance reasons you're recommended to not return

any excessive data structures.

If you want to access any variables within your callback function, you

can bind arbitrary data to a callback closure like this:

<div class="highlight highlight-text-html-php"><pre>$loop->addReadStream($stream, function ($stream) use ($name) {

echo $name . ' said: ' . fread($stream);

});</pre></div>

See also <a href="https://github.com/reactphp/event-loop/blob/v1.6.0/examples">example #11</a>.

You can invoke <a href="#removereadstream"><code>removeReadStream()</code></a> to remove the

read event listener for this stream.

The execution order of listeners when multiple streams become ready at

the same time is not guaranteed.

Some event loop implementations are known to only trigger the listener if

the stream becomes readable (edge-triggered) and may not trigger if the

stream has already been readable from the beginning.

This also implies that a stream may not be recognized as readable when data

is still left in PHP's internal stream buffers.

As such, it's recommended to use <code>stream_set_read_buffer($stream, 0);</code>

to disable PHP's internal read buffer in this case.

<div class="markdown-heading"><h4 class="heading-element">addWriteStream()</h4><a id="addwritestream" class="anchor" aria-label="Permalink: addWriteStream()" href="#addwritestream"></a></div>

Advanced! Note that this low-level API is considered advanced usage.

Most use cases should probably use the higher-level

<a href="../stream/#writablestreaminterface">writable Stream API</a>

instead.

</blockquote>

The <code>addWriteStream(resource $stream, callable $callback): void</code> method can be used to

The first parameter MUST be a valid stream resource that supports

checking whether it is ready to write by this loop implementation.

A single stream resource MUST NOT be added more than once.

Instead, either call <a href="#removewritestream"><code>removeWriteStream()</code></a> first or

react to this event with a single listener and then dispatch from this

listener. This method MAY throw an <code>Exception</code> if the given resource type

is not supported by this loop implementation.

The second parameter MUST be a listener callback function that accepts

the stream resource as its only parameter.

If you don't use the stream resource inside your listener callback function

you MAY use a function which has no parameters at all.

The listener callback function MUST NOT throw an <code>Exception</code>.

The return value of the listener callback function will be ignored and has

no effect, so for performance reasons you're recommended to not return

any excessive data structures.

If you want to access any variables within your callback function, you

can bind arbitrary data to a callback closure like this:

<div class="highlight highlight-text-html-php"><pre>$loop->addWriteStream($stream, function ($stream) use ($name) {

fwrite($stream, 'Hello ' . $name);

});</pre></div>

See also <a href="https://github.com/reactphp/event-loop/blob/v1.6.0/examples">example #12</a>.

You can invoke <a href="#removewritestream"><code>removeWriteStream()</code></a> to remove the

write event listener for this stream.

The execution order of listeners when multiple streams become ready at

the same time is not guaranteed.

<div class="markdown-heading"><h4 class="heading-element">removeReadStream()</h4><a id="removereadstream" class="anchor" aria-label="Permalink: removeReadStream()" href="#removereadstream"></a></div>

The <code>removeReadStream(resource $stream): void</code> method can be used to

remove the read event listener for the given stream.

Removing a stream from the loop that has already been removed or trying

to remove a stream that was never added or is invalid has no effect.

<div class="markdown-heading"><h4 class="heading-element">removeWriteStream()</h4><a id="removewritestream" class="anchor" aria-label="Permalink: removeWriteStream()" href="#removewritestream"></a></div>

The <code>removeWriteStream(resource $stream): void</code> method can be used to

remove the write event listener for the given stream.

Removing a stream from the loop that has already been removed or trying

to remove a stream that was never added or is invalid has no effect.

<div class="markdown-heading"><h2 class="heading-element">Install</h2><a id="install" class="anchor" aria-label="Permalink: Install" href="#install"></a></div>

The recommended way to install this library is <a href="https://getcomposer.org/" rel="nofollow">through Composer</a>.

<a href="https://getcomposer.org/doc/00-intro.md" rel="nofollow">New to Composer?</a>

This project follows <a href="https://semver.org/" rel="nofollow">SemVer</a>.

This will install the latest supported version:

<div class="highlight highlight-source-shell"><pre>composer require react/event-loop:^1.6</pre></div>

See also the <a href="changelog.html">CHANGELOG</a> for details about version upgrades.

This project aims to run on any platform and thus does not require any PHP

extensions and supports running on legacy PHP 5.3 through current PHP 8+ and

HHVM.

It's highly recommended to use the latest supported PHP version for this project.

Installing any of the event loop extensions is suggested, but entirely optional.

See also <a href="#loop-implementations">event loop implementations</a> for more details.

<div class="markdown-heading"><h2 class="heading-element">Tests</h2><a id="tests" class="anchor" aria-label="Permalink: Tests" href="#tests"></a></div>

To run the test suite, you first need to clone this repo and then install all

dependencies <a href="https://getcomposer.org/" rel="nofollow">through Composer</a>:

<div class="highlight highlight-source-shell"><pre>composer install</pre></div>

To run the test suite, go to the project root and run:

<div class="highlight highlight-source-shell"><pre>vendor/bin/phpunit</pre></div>

<div class="markdown-heading"><h2 class="heading-element">License</h2><a id="license" class="anchor" aria-label="Permalink: License" href="#license"></a></div>

MIT, see <a href="license.html">LICENSE file</a>.

<ul>

<li>See our <a href="../stream/">Stream component</a> for more

information on how streams are used in real-world applications.</li>

<li>See our <a href="https://github.com/reactphp/react/wiki/Users">users wiki</a> and the

<a href="https://packagist.org/packages/react/event-loop/dependents" rel="nofollow">dependents on Packagist</a>

for a list of packages that use the EventLoop in real-world applications.</li>

</ul>

</main>

<a href="../event-loop/">EventLoop</a>

v1.6.0

</button>

Read the documentation of development and older versions on GitHub:

<li>

master

</a>

</li>

<li>

v1.5.0

</a>

</li>

<li>

v1.4.0

</a>

</li>

<li>

v1.3.0

</a>

</li>

<li>

v1.2.0

</a>

</li>

<li>

v1.1.1

</a>

</li>

<li>

v1.1.0

</a>

</li>

<li>

View remainder of file in raw view

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

FilesExpand file tree

index.html

Latest commit

History

index.html

File metadata and controls