PHP mysqli_poll() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
MySQLi

Definition

In PHP, mysqli_poll() waits until one or more asynchronous MySQLi connections have results ready, then returns how many connections are ready to read.

It works with non-blocking queries started with MYSQLI_ASYNC, and you normally follow up with mysqli_reap_async_query(). This is an advanced mysqlnd feature — beginners should master mysqli_query() and prepared statements first.

Syntax

Call mysqli_poll() with the values you need. Start with this line.

PHP
$ready = mysqli_poll($read, $error, $reject, 1);
CallWhat it does
mysqli_poll($read, $error, $reject, 1)Waits up to 1 second for async connections to become ready.
mysqli_poll($links, $errors, $reject, 0, 500000)Waits up to 0.5 seconds using the microseconds argument.
if (mysqli_poll($r, $e, $j, 1)) { /* reap */ }Only reaps results when at least one link is ready.

Honest complexity note: async MySQLi (poll + reap_async_query) is niche, mysqlnd-only, and not used in typical beginner apps. Prefer ordinary mysqli_query() or mysqli_prepare(). Treat this page as awareness, not a first learning path.

Library declarations
PHP
mysqli_poll(?array &$read, ?array &$error, array &$reject, int $seconds, int $microseconds = 0): int|false

Parameters

ParameterDescription
readOptional by reference. Connections to check for readable async results; rewritten to the ready subset.
errorOptional by reference. Connections that had errors; rewritten to the error subset.
rejectRequired by reference. Connections rejected because they had nothing async to poll.
secondsRequired. Whole seconds to wait (non-negative).
microsecondsOptional. Extra microseconds to wait. Default 0.

Return Value

Return ValueDescription
int|falseThe number of ready connections on success, or false on failure.

PHP Examples

Example 1 — Conceptual Async Poll Loop

Sketch the poll/reap pattern with fixed sample output. This is advanced — skip it until you need concurrency.

PHP
<?php
// Advanced sketch (mysqlnd + MYSQLI_ASYNC). Fixed sample output for the tutorial.
$link = mysqli_connect("localhost", "demo_user", "demo_pass", "app_db");
mysqli_query($link, "SELECT 'test' AS v", MYSQLI_ASYNC);

$all = [$link];
$processed = 0;
do {
    $read = $error = $reject = [];
    foreach ($all as $l) {
        $read[] = $error[] = $reject[] = $l;
    }
    if (!mysqli_poll($read, $error, $reject, 1)) {
        continue;
    }
    foreach ($read as $l) {
        if ($result = mysqli_reap_async_query($l)) {
            $row = mysqli_fetch_row($result);
            echo $row[0], PHP_EOL;
            mysqli_free_result($result);
        }
        $processed++;
    }
} while ($processed < count($all));

mysqli_close($link);

How It Works

  1. MYSQLI_ASYNC starts the query without waiting for the full result.
  2. mysqli_poll() blocks briefly until a connection is ready.
  3. mysqli_reap_async_query() collects the finished result.
  4. Beginners can ignore this pattern and use normal query() instead.

Example 2 — When Poll Returns Zero

A timeout with nothing ready returns 0 — keep waiting or abort.

PHP
<?php
$read = $error = $reject = [];
// No async work queued in this demo — poll simply times out.
$n = 0; // sample stand-in for mysqli_poll($read, $error, $reject, 1)
echo "Ready links: ", $n, PHP_EOL;
echo "Nothing to reap yet.", PHP_EOL;

How It Works

  1. 0 means the wait ended without a ready connection.
  2. That is normal when the server is still working.
  3. Loops often continue until a positive count appears.
  4. false (not shown) would mean the poll call itself failed.

Example 3 — Beginner Alternative: Plain Query

The everyday approach that replaces almost all poll use cases.

PHP
<?php
$mysqli = mysqli_connect("localhost", "demo_user", "demo_pass", "app_db");
$result = mysqli_query($mysqli, "SELECT 'test' AS v");
$row = mysqli_fetch_assoc($result);
echo $row["v"], PHP_EOL;
mysqli_free_result($result);
mysqli_close($mysqli);

How It Works

  1. mysqli_query() waits for the result in one step.
  2. No poll or reap_async_query is required.
  3. This is the right default for learning and most apps.
  4. Revisit poll only for specialized concurrent mysqlnd workloads.

Frequently Asked Questions

It waits for asynchronous MySQLi connections to become ready and returns how many can be read.
Almost never. Learn mysqli_query() and mysqli_prepare() first.
Start queries with MYSQLI_ASYNC, poll for readiness, then mysqli_reap_async_query() to collect results.
No. MYSQLI_ASYNC polling is for non-prepared queries only.
Yes. The async poll/reap feature is available with the mysqlnd driver.

Next: mysqli_prepare()

mysqli_prepare() sends an SQL template with ? placeholders to MySQL and returns a mysqli_s.

mysqli_prepare() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful