Nette SafeStream
****************

.[perex]
Nette SafeStream, her dosya okuma ve yazma işleminin yalıtılmış biçimde gerçekleşmesini güvence altına alır. Bu, hiçbir iş parçacığının henüz tümüyle yazılmamış bir dosyayı okumaya başlamayacağı ve birden çok iş parçacığının aynı dosyanın üzerine yazmayacağı anlamına gelir.

Kurulum:

```shell
composer require nette/safe-stream
```


Ne İşe Yarar?
-------------

Yalıtılmış işlemler aslında ne işe yarar? Bir dosyaya yinelemeli yazan ve sonra aynı dizeyi ondan okuyan basit bir örnekle başlayalım:

```php
$s = str_repeat('Long String', 10000);

$counter = 1000;
while ($counter--) {
	file_put_contents('file', $s); // yaz
	$readed = file_get_contents('file'); // oku
	if ($s !== $readed) { // denetle
		echo 'strings are different!';
	}
}
```

`echo 'strings are different!'` çağrısının asla gerçekleşemeyeceği görünebilir. Tam tersi doğrudur. Bu betiği iki tarayıcı sekmesinde aynı anda çalıştırmayı deneyin. Hata neredeyse hemen ortaya çıkacak.

Sekmelerden biri dosyayı, diğeri onu tümüyle yazmayı bitirmemişken okuyacak, dolayısıyla içerik eksik olacak.

Bu yüzden kod, aynı anda birden çok kez (yani birden çok iş parçacığında) yürütülürse güvenli değildir. Bu, internette sıra dışı bir durum değildir; çünkü sunucular sıklıkla çok sayıda kullanıcıya aynı anda yanıt verir. Uygulamanızın birden çok iş parçacığında yürütüldüğünde bile güvenilir çalışmasını güvence altına almak (thread-safe) çok önemlidir. Aksi hâlde veri yitimi ve saptaması zor hatalar ortaya çıkabilir.

Ancak gördüğünüz gibi PHP'nin yerel dosya okuma ve yazma fonksiyonları yalıtılmış ya da atomik değildir.


SafeStream Nasıl Kullanılır?
----------------------------

SafeStream, standart PHP fonksiyonlarını kullanarak dosyaların yalıtılmış biçimde okunup yazılabildiği güvenli bir protokol oluşturur. Dosya adının başına `nette.safe://` koymanız yeter:

```php
file_put_contents('nette.safe://file', $s);
$s = file_get_contents('nette.safe://file');
```

SafeStream, bir anda en çok bir iş parçacığının dosyaya yazabilmesini sağlar. Diğer iş parçacıkları bir kuyrukta bekler. Hiçbir iş parçacığı yazmıyorsa, istediği kadar iş parçacığı dosyayı paralel okuyabilir.

Protokolle tüm yaygın PHP fonksiyonları kullanılabilir, örneğin:

```php
// 'r' yalnızca okumak için açmak anlamına gelir
$handle = fopen('nette.safe://file.txt', 'r');

$ini = parse_ini_file('nette.safe://config.ini');
```


Sınırlamalar
------------

SafeStream, dosya içeriğinin okunmasını ve yazılmasını yalıtır, ama her işlemi atomik kılamaz. Şu sınırları aklınızda tutun:

- **Dosya bilgisi yalıtılmaz.** Yalnızca üstveri sorgulayan `file_exists()`, `filesize()` ya da `is_file()` gibi fonksiyonlar kilitlemeye katılmaz. Başka bir iş parçacığının o an yazmakta olduğu bir dosya hakkında bilgi döndürebilirler.
- **Windows'ta açık bir dosyayı silme.** Unix'in tersine Windows, başka bir iş parçacığının o an açık tuttuğu bir dosyayı silmenize izin vermez, dolayısıyla `unlink('nette.safe://file')` başarısız olabilir.
- **Tamamlanmamış yazmaların otomatik geri alınması.** Bir yazma yarıda başarısız olursa (örneğin disk dolarsa), dosya kapatılırken SafeStream onu yazmaya başlamadan önceki boyutuna kırpar, böylece asla yarım yazılmış veri bırakmaz.

Daha yeni bir sürüme yükseltiyorsanız [yükseltme |upgrading] sayfasına bakın.


{{sitename: Nette Dokümantasyonu}}