Skip to content

Commit

Permalink
Add serializer example to Subprocess module docs (chapel-lang#23469)
Browse files Browse the repository at this point in the history
This PR adds an example of how to use serializers to achieve binary IO
with the subprocess module, as an alternative to the deprecated ``kind``
field.

This PR also adds some documentation to the overlooked
``withSerializer`` and ``withDeserializer`` methods.

[reviewed-by @DanilaFe]
  • Loading branch information
benharsh authored Sep 20, 2023
2 parents 0987781 + 493ec36 commit 8773b74
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 6 deletions.
40 changes: 34 additions & 6 deletions modules/standard/IO.chpl
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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);
Expand Down
43 changes: 43 additions & 0 deletions modules/standard/Subprocess.chpl
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,49 @@ 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 enable
binary IO and set the desired endianness. The 1.32 release introduced
:ref:`serializers<ioSerializers>`, 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
Please refer to :type:`~IO.binarySerializer` and :type:`~IO.binaryDeserializer`
for more information on their supported format.
*/
module Subprocess {
public use IO;
Expand Down

0 comments on commit 8773b74

Please sign in to comment.