wincache_ucache_cas — Funktion · PHP-Referenz

Signatur

wincache_ucache_cas(string $key, int $old_value, int $new_value): bool

Beschreibung

wincache_ucache_cas führt eine atomische Compare-and-Swap-Operation (CAS) auf einem Eintrag im WinCache-Benutzercache durch. Das bedeutet: Nur wenn der aktuell im Cache gespeicherte Wert exakt mit old_value übereinstimmt, wird er durch new_value ersetzt. Andernfalls bleibt der Wert unverändert und die Funktion gibt false zurück.

Diese Funktion ist besonders nützlich für nebenläufige Szenarien, in denen mehrere PHP-Prozesse oder -Threads gleichzeitig auf denselben Cache-Eintrag zugreifen könnten. Durch die Atomizität der Operation werden Race Conditions vermieden, ohne dass explizite Sperren (Locks) benötigt werden.

Typische Anwendungsfälle sind verteilte Zähler, optimistische Sperrmechanismen oder das sichere Aktualisieren von Zustandswerten, die von konkurrierenden Prozessen gelesen und geschrieben werden. Der Schlüssel muss bereits im Cache vorhanden sein; existiert er nicht, gibt die Funktion false zurück.

Hinweis: Diese Funktion steht nur unter Windows zur Verfügung und erfordert die WinCache-Erweiterung. Sowohl old_value als auch new_value müssen ganzzahlige Werte sein.

Parameter

Name	Typ	Beschreibung
$key Pflicht	string	Der Schlüssel des Cache-Eintrags, der verglichen und ggf. aktualisiert werden soll.
$old_value Pflicht	int	Der erwartete aktuelle Wert im Cache. Die Operation wird nur durchgeführt, wenn der gespeicherte Wert exakt diesem Wert entspricht.
$new_value Pflicht	int	Der neue Wert, der dem Cache-Eintrag zugewiesen wird, wenn der Vergleich erfolgreich war.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Vergleich erfolgreich war und der Wert ersetzt wurde. Gibt false zurück, wenn der gespeicherte Wert nicht mit old_value übereinstimmt, der Schlüssel nicht im Cache vorhanden ist oder ein Fehler aufgetreten ist.

Beispiele

Atomischer Zähler mit CAS absichern

<?php
// Zähler initial auf 0 setzen
wincache_ucache_set('counter', 0);

// Atomisch von 0 auf 1 erhöhen
$old = (int) wincache_ucache_get('counter');
$new = $old + 1;

if (wincache_ucache_cas('counter', $old, $new)) {
    echo "Zähler erfolgreich von {$old} auf {$new} erhöht.";
} else {
    echo "CAS fehlgeschlagen – ein anderer Prozess hat den Wert zwischenzeitlich geändert.";
}

Zähler erfolgreich von 0 auf 1 erhöht.

Retry-Schleife mit CAS für nebenläufige Updates

<?php
// Initialisierung des Wertes
wincache_ucache_set('status', 0);

$maxRetries = 5;
$updated = false;

for ($i = 0; $i < $maxRetries; $i++) {
    $current = (int) wincache_ucache_get('status');
    
    // Nur aktualisieren, wenn Status noch 0 ist
    if ($current !== 0) {
        echo "Status ist bereits {$current}, kein Update nötig.";
        break;
    }

    if (wincache_ucache_cas('status', 0, 1)) {
        echo "Status erfolgreich von 0 auf 1 gesetzt.";
        $updated = true;
        break;
    }

    // Kurz warten, bevor erneut versucht wird
    usleep(1000);
}

if (!$updated) {
    echo "Update nach {$maxRetries} Versuchen fehlgeschlagen.";
}

Status erfolgreich von 0 auf 1 gesetzt.

// Wichtig · Fallstricke

Nur unter Windows verfügbar: wincache_ucache_cas ist ausschließlich auf Windows-Systemen mit installierter WinCache-Erweiterung verfügbar. Auf Linux- oder macOS-Systemen steht diese Funktion nicht zur Verfügung.

Nur für ganzzahlige Werte: Die CAS-Operation funktioniert ausschließlich mit int-Werten. Wird ein nicht-ganzzahliger Wert im Cache gespeichert, schlägt der Vergleich fehl. Für komplexere Datenstrukturen muss ein eigenes Locking-Konzept implementiert werden.

Kein automatisches Erstellen: Existiert der angegebene Schlüssel noch nicht im Cache, gibt die Funktion false zurück, ohne einen neuen Eintrag anzulegen. Der Eintrag muss zuvor z. B. mit wincache_ucache_set erstellt werden.

Siehe auch

wincache_ucache_get wincache_ucache_set wincache_ucache_add wincache_ucache_inc wincache_ucache_dec wincache_ucache_delete