| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| rfc:dedicated_stream_bucket [2024/01/19 14:20] – kocsismate | rfc:dedicated_stream_bucket [2024/04/11 18:16] (current) – kocsismate |
|---|
| * Date: 2024-01-19 | * Date: 2024-01-19 |
| * Author: Máté Kocsis <kocsismate@php.net> | * Author: Máté Kocsis <kocsismate@php.net> |
| * Status: Draft | * Status: Implemented |
| * Target: next minor version (possibly PHP 8.4) | * Target: next minor version (possibly PHP 8.4) |
| | * Implementation: https://github.com/php/php-src/pull/13111 |
| |
| ===== Introduction ===== | ===== Introduction ===== |
| When using user filters for stream processing, one of the fundamental concepts is stream buckets. A stream bucket is effectively a chunk of stream which can be extracted from bucket brigades. Most probably, this metaphor comes from firefighting [[https://en.wikipedia.org/wiki/Bucket_brigade|bucket brigades]] who pass buckets of water to each other, standing in a chain. | When using user filters for stream processing, one of the fundamental concepts is stream buckets. A stream bucket is effectively a chunk of stream which can be extracted from bucket brigades. Most probably, this metaphor comes from firefighting [[https://en.wikipedia.org/wiki/Bucket_brigade|bucket brigades]] who pass buckets of water to each other, standing in a chain. |
| |
| Back to our original topic, here is an example for a very basic stream filter: | Back to our original topic, here is an example of a very basic stream filter: |
| |
| <code PHP> | <code PHP> |
| //Disclaimer: the example is copy-pasted from https://stackoverflow.com/questions/27103269/what-is-a-bucket-brigade. Courtesy of Bob for providing such an exceptional answer to explain the behavior of user stream filters.// | //Disclaimer: the example is copy-pasted from https://stackoverflow.com/questions/27103269/what-is-a-bucket-brigade. Courtesy of Bob for providing such an exceptional answer to explain the behavior of user stream filters.// |
| |
| ''$in'' and ''$out'' are the two sides of the stream bucket brigade: items come from the former one, and you have to pass them to the latter one. The ''stream_bucket_make_writeable()'' function can be used to get the bucket from the brigade, while the ''stream_bucket_new()'' function is used to create a new bucket. | ''$in'' and ''$out'' are the two sides of the stream bucket brigade: items come from the former one, which have to be passed to the latter one. The ''stream_bucket_make_writeable()'' function can be used to get the bucket from the brigade, while the ''stream_bucket_new()'' function is used to create a new bucket. |
| |
| ===== Discussion ===== | ===== Discussion ===== |
| ==== Lack of a dedicated class ==== | ==== Lack of a dedicated class ==== |
| |
| The original problem why this RFC is submitted is that there is no dedicated class for stream buckets: ''stream_bucket_make_writeable()'' and ''stream_bucket_new()'' create just ''stdClass'' instances and fill in their ''$bucket'', ''$data'', and ''$datalen'' properties on the go. | The original problem why this RFC is submitted is that there is no dedicated class for stream buckets: ''stream_bucket_make_writeable()'' and ''stream_bucket_new()'' create ''stdClass'' instances and fill in their ''$bucket'', ''$data'', as well as ''$datalen'' properties on the fly. |
| |
| <code PHP> | <code PHP> |
| ===== The $bucket property ==== | ===== The $bucket property ==== |
| |
| The ''$bucket'' property is a stream bucket resource which is about to be migrated to an object in a major PHP version as per [[rfc:resource_to_object_conversion|Resource to object conversion]]. However, this property won't be useful anymore as soon as it becomes an object, since it can be inlined directly into the containing stream bucket class. Therefore, this RFC proposes to get rid of this property when the conversion happens. Until then, a deprecation is emitted in order to let people know about the planned change. | The ''$bucket'' property is a stream bucket resource which is about to be migrated to an object in a major PHP version as per [[rfc:resource_to_object_conversion|Resource to object conversion]]. However, this property won't be useful anymore as soon as it becomes an object, since it can be inlined directly into the containing stream bucket class. Therefore, this RFC proposes to emit a deprecation notice as soon as the resource to object migration happens (in a major PHP version). The consequent major version should then get rid of the property altogether. |
| |
| ===== The $datalen property ==== | ===== The $datalen property ==== |
| The name of this property doesn't conform to the currently used naming conventions: we usually try to avoid abbreviations whenever possible (e.g. when the full name is not too verbose, and the abbreviation is not an extremely common term - like ''$id''). Since the difference between ''len'' and ''length'' is just 3 characters, I don't think that using this abbreviation is really worth it. Therefore, this RFC proposes to add a ''$dataLength'' property. | The name of this property doesn't conform to the currently used naming conventions: we usually try to avoid abbreviations whenever possible (e.g. when the full name is not too verbose, and the abbreviation is not an extremely common term - like ''$id''). Since the difference between ''len'' and ''length'' is just 3 characters, I don't think that using this abbreviation is really worth it. Therefore, this RFC proposes to add a ''$dataLength'' property. |
| |
| Additionally, the ''$datalen'' property would become deprecated in favor of ''$dataLength'' in the subsequent minor or major version after the targeted version (possibly PHP 8.5 or PHP 9.0), and would be removed in the next to next major version (possibly PHP 10). | Additionally, the ''$datalen'' property would become deprecated in favor of ''$dataLength'' in the subsequent minor or major version after the target version (possibly PHP 8.5 or PHP 9.0), and would be removed in the next to next major version (possibly PHP 10). |
| |
| ===== The proposed class ==== | ===== The proposed class ==== |
| /** | /** |
| * @var resource | * @var resource |
| * @deprecated | * @deprecated after resource to object conversion happens |
| */ | */ |
| public $bucket; | public $bucket; |
| public string $data; | public string $data; |
| /** @deprecated */ | /** @deprecated in PHP 8.5 or PHP 9.0 whichever comes next */ |
| public int $datalen; | public int $datalen; |
| public int $dataLength; | public int $dataLength; |
| ===== Vote ===== | ===== Vote ===== |
| |
| The vote requires 2/3 majority in order to be accepted. | The vote requires 2/3 majority in order to be accepted. The vote is going to be closed on 2024-04-11 10:00 UTC. |
| |
| ==== Primary vote ==== | ==== Primary vote ==== |
| |
| <doodle title="Add the StreamBucket class as proposed?" auth="kocsismate" voteType="single" closed="true" closeon="2024-03-19T10:00:00Z"> | <doodle title="Add the StreamBucket class as proposed?" auth="kocsismate" voteType="single" closed="no" closeon="2024-04-11T10:00:00Z"> |
| * yes | * yes |
| * no | * no |
| </doodle> | </doodle> |
| |