From fc887b2742763ab2ed0927d728a12aa023e26b34 Mon Sep 17 00:00:00 2001 From: Ben Harshbarger Date: Wed, 20 Sep 2023 00:17:45 -0700 Subject: [PATCH 1/3] Add documentation for withSerializer/withDeserializer Signed-off-by: Ben Harshbarger --- modules/standard/IO.chpl | 40 ++++++++++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/modules/standard/IO.chpl b/modules/standard/IO.chpl index f4a89aff01c7..daaf0a2258d4 100644 --- a/modules/standard/IO.chpl +++ b/modules/standard/IO.chpl @@ -3831,15 +3831,29 @@ proc ref fileWriter.deinit() { } } -// Convenience for forms like 'r.withDeserializer(defaultDeserializer)` -@chpldoc.nodoc +/* + Create and return an alias of this ``fileReader`` configured to use + ``deserializerType`` for deserialization. The provided ``deserializerType`` + must be able to be default-initialized. + + .. warning:: + + It is an error for the returned alias to outlive the original ``fileReader``. +*/ proc fileReader.withDeserializer(type deserializerType) : fileReader(this._kind, this.locking, deserializerType) { var des : deserializerType; return withDeserializer(des); } -@chpldoc.nodoc +/* + Create and return an alias of this ``fileReader`` configured to use + ``deserializer`` for deserialization. + + .. warning:: + + It is an error for the returned alias to outlive the original ``fileReader``. +*/ proc fileReader.withDeserializer(in deserializer: ?dt) : fileReader(this._kind, this.locking, dt) { var ret = new fileReader(this._kind, this.locking, dt); ret._deserializer = new shared _serializeWrapper(dt, deserializer); @@ -3852,15 +3866,29 @@ proc fileReader.withDeserializer(in deserializer: ?dt) : fileReader(this._kind, return ret; } -// Convenience for forms like 'w.withSerializer(defaultSerializer)` -@chpldoc.nodoc +/* + Create and return an alias of this ``fileWriter`` configured to use + ``serializerType`` for serialization. The provided ``serializerType`` must be + able to be default-initialized. + + .. warning:: + + It is an error for the returned alias to outlive the original ``fileWriter``. +*/ proc fileWriter.withSerializer(type serializerType) : fileWriter(this._kind, this.locking, serializerType) { var ser : serializerType; return withSerializer(ser); } -@chpldoc.nodoc +/* + Create and return an alias of this ``fileWriter`` configured to use + ``serializer`` for serialization. + + .. warning:: + + It is an error for the returned alias to outlive the original ``fileWriter``. +*/ proc fileWriter.withSerializer(in serializer: ?st) : fileWriter(this._kind, this.locking, st) { var ret = new fileWriter(this._kind, this.locking, st); ret._serializer = new shared _serializeWrapper(st, serializer); From 178ade07a0b86ae34e86be1731f5e0ffb04f562e Mon Sep 17 00:00:00 2001 From: Ben Harshbarger Date: Wed, 20 Sep 2023 00:18:02 -0700 Subject: [PATCH 2/3] Add example for how to replace usage of 'kind' field for binary IO Signed-off-by: Ben Harshbarger --- modules/standard/Subprocess.chpl | 40 ++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/modules/standard/Subprocess.chpl b/modules/standard/Subprocess.chpl index 6f627c998101..3cb5f8412e2f 100644 --- a/modules/standard/Subprocess.chpl +++ b/modules/standard/Subprocess.chpl @@ -127,6 +127,46 @@ other task is consuming it. locale. In this circumstance, the program will halt with an error message. These scenarios do work when using GASNet instead of the ugni layer. +The Deprecated 'kind' Field +--------------------------- + +Prior to the 1.32 release, configuring a :type:`subprocess` record to use +binary IO required using the ``kind`` field (of type ``iokind``) to set the +desired endianness. The 1.32 release introduced +:ref:`serializers`, and deprecated use of the ``iokind`` type in +favor of using Serializers and Deserializers to configure a given +:type:`~IO.fileWriter` or :type:`~IO.fileReader` for a desired format. + +Users may now create aliases of ``stdin`` and ``stdout`` with different +serialization formatting by using the :proc:`~IO.fileWriter.withSerializer` and +:proc:`~IO.fileReader.withDeserializer` methods. For example, consider the +following program that writes the numbers ``1`` through ``10`` in binary to the +``hexdump`` utility: + +.. code-block:: chapel + + use IO, Subprocess; + + var sub = spawn(["hexdump", "-C"], stdin=pipeStyle.pipe, stdout=pipeStyle.pipe); + + // Use 'withSerializer' to create a binary-serializing alias of 'sub.stdin' + var bin = sub.stdin.withSerializer(binarySerializer); + + for i in 1..10 do bin.write(i:uint(8)); + + sub.communicate(); + + var line : string; + while sub.stdout.readLine(line) do + write(line); + +This program prints: + +.. code-block:: text + + 00000000 01 02 03 04 05 06 07 08 09 0a |..........| + 0000000a + */ module Subprocess { public use IO; From 493ec36e95b7e3410b3111b850a90fe14981405f Mon Sep 17 00:00:00 2001 From: Ben Harshbarger Date: Wed, 20 Sep 2023 09:37:14 -0700 Subject: [PATCH 3/3] More information on binary IO Signed-off-by: Ben Harshbarger --- modules/standard/Subprocess.chpl | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/modules/standard/Subprocess.chpl b/modules/standard/Subprocess.chpl index 3cb5f8412e2f..161bbde9b232 100644 --- a/modules/standard/Subprocess.chpl +++ b/modules/standard/Subprocess.chpl @@ -131,8 +131,8 @@ The Deprecated 'kind' Field --------------------------- Prior to the 1.32 release, configuring a :type:`subprocess` record to use -binary IO required using the ``kind`` field (of type ``iokind``) to set the -desired endianness. The 1.32 release introduced +binary IO required using the ``kind`` field (of type ``iokind``) to enable +binary IO and set the desired endianness. The 1.32 release introduced :ref:`serializers`, and deprecated use of the ``iokind`` type in favor of using Serializers and Deserializers to configure a given :type:`~IO.fileWriter` or :type:`~IO.fileReader` for a desired format. @@ -167,6 +167,9 @@ This program prints: 00000000 01 02 03 04 05 06 07 08 09 0a |..........| 0000000a +Please refer to :type:`~IO.binarySerializer` and :type:`~IO.binaryDeserializer` +for more information on their supported format. + */ module Subprocess { public use IO;