develooper Front page | perl.perl5.porters | Postings from November 2017

[perl #132422] [PATCH] IO::Socket Documentation

Thread Previous | Thread Next
From:
James E Keenan via RT
Date:
November 20, 2017 14:41
Subject:
[perl #132422] [PATCH] IO::Socket Documentation
Message ID:
rt-4.0.24-6173-1511188900-1515.132422-15-0@perl.org
On Fri, 10 Nov 2017 04:42:30 GMT, capoeirab@cpan.org wrote:
> This is a bug report for perl from capoeirab@cpan.org,
> generated with the help of perlbug 1.40 running under perl 5.27.6.
> 
> 
> -----------------------------------------------------------------
> [Please describe your issue here]
> 
> The documentation for IO::Socket hasn't been updated in quite some
> time.
> This patch goes through modernizing the documentation and providing
> many
> more examples. Next up will be IO::Socket::INET and IO::Socket::UNIX.
> 
> Once all of the documentation has been updated, hopefully the updates
> will make their way back to the CPAN releases for the IO:: dist.
> 
> 

Thank you for taking the time to review the IO::Socket documentation and submit a patch.

Because there are quite a lot of revisions in your patch, you should expect a certain amount of back-and-forth with respect to further revisions before this is applied to blead.

I am not an expert on sockets, so I'm not going to attempt to review the entire patch here.  I hope that other readers will contribute constructive comments.

I will, however, comment on your revisions to the SYNOPSIS.  Granted, the current synopsis is insufficient.  However, we generally follow a style in which the synopsis focuses on terse descriptions of the most important methods or functions which a module provides.  More detailed information on particular methods, including more fully fleshed-out examples should be deferred to the sections on those methods or, perhaps, to an EXAMPLES section later in the documentation.  More specifically:

 =head1 SYNOPSIS
 
-    use IO::Socket;

We don't need any of the next four lines in SYNOPSIS.

+    #!/usr/bin/env perl
+    use strict;
+    use warnings;
+    use feature 'say';
+
+    use IO::Socket qw(AF_INET AF_UNIX SOCK_STREAM SHUT_WR);
+
+    # create a new AF_INET socket

We don't need the 'my' in SYNOPSIS.

+    my $sock = IO::Socket->new(Domain => AF_INET);

The next two lines should go in discussion of new().

+    # which is the same as
+    $sock = IO::Socket::INET->new();
+
+    # create a new AF_UNIX socket
+    $sock = IO::Socket->new(Domain => AF_UNIX);

Same as above.

+    # which is the same as
+    $sock = IO::Socket::UNIX->new();
+

The balance of the revisions should be moved to an EXAMPLES section (once the code is verified).

+    # Let's create a TCP server on localhost:3333
+    my $server = IO::Socket->new(
+        Domain => AF_INET,
+        Type => SOCK_STREAM,
+        Proto => 'tcp',
+        LocalHost => '0.0.0.0',
+        LocalPort => 3333,
+        ReusePort => 1,
+        Listen => 5,
+    ) || die "Can't open socket: $@";
+    say "Waiting on 3333";
+
+    while (1) {
+        # waiting for a new client connection
+        my $client = $server->accept();
+
+        # get information about a newly connected client
+        my $client_address = $client->peerhost();
+        my $client_port = $client->peerport();
+        say "Connection from $client_address:$client_port";
+
+        # read up to 1024 characters from the connected client
+        my $data = "";
+        $client->recv($data, 1024);
+        say "received data: $data";
+
+        # write response data to the connected client
+        $data = "ok";
+        $client->send($data);
+
+        # notify client that response has been sent
+        $client->shutdown(SHUT_WR);
+    }
+
+    $server->close();
+
+
+    # A client for such a server could be
+    my $client = IO::Socket->new(
+        Domain => AF_INET,
+        Type => SOCK_STREAM,
+        proto => 'tcp',
+        PeerPort => 3333,
+        PeerHost => '0.0.0.0',
+    ) || die "Can't open socket: $@";
+
+    say "Sending Hello World!";
+    my $size = $client->send("Hello World!");
+    say "Sent data of length: $size";
+
+    $client->shutdown(SHUT_WR);
+
+    my $buffer;
+    $client->recv($buffer, 1024);
+    say "Got back $buffer";
+
+    $client->close();

The only IO::Socket methods you used in these examples apart from new() were accept() and close().  Are they used often enough -- not just in creation of servers -- to warrant their being placed in the SYNOPSIS?  Are there any other IO::Socket methods whose importance warrants their being mentioned in the SYNOPSIS?



> [Please do not change anything below this line]
> -----------------------------------------------------------------
> ---
> Flags:
>     category=library
>     severity=low
>     Type=Patch
>     PatchStatus=HasPatch
>     module=IO::Socket
> ---
> Site configuration information for perl 5.27.6:
> 
> Configured by cwhitener at Thu Nov  9 22:04:00 EST 2017.
> 
> Summary of my perl5 (revision 5 version 27 subversion 6)
> configuration:
>   Derived from: 29d69c3c41c7e93f884256b1087face64d5fdd1e
>   Platform:
>     osname=linux
>     osvers=4.10.0-19-generic
>     archname=x86_64-linux
>     uname='linux lappy 4.10.0-19-generic #21-ubuntu smp thu apr 6
> 17:04:57 utc 2017 x86_64 x86_64 x86_64 gnulinux '
>     config_args='-des -Dusedevel'
>     hint=recommended
>     useposix=true
>     d_sigaction=define
>     useithreads=undef
>     usemultiplicity=undef
>     use64bitint=define
>     use64bitall=define
>     uselongdouble=undef
>     usemymalloc=n
>     default_inc_excludes_dot=define
>     bincompat5005=undef
>   Compiler:
>     cc='cc'
>     ccflags ='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-
> strong -I/usr/local/include -D_LARGEFILE_SOURCE
> -D_FILE_OFFSET_BITS=64'
>     optimize='-O2'
>     cppflags='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-
> strong -I/usr/local/include'
>     ccversion=''
>     gccversion='7.2.0'
>     gccosandvers=''
>     intsize=4
>     longsize=8
>     ptrsize=8
>     doublesize=8
>     byteorder=12345678
>     doublekind=3
>     d_longlong=define
>     longlongsize=8
>     d_longdbl=define
>     longdblsize=16
>     longdblkind=3
>     ivtype='long'
>     ivsize=8
>     nvtype='double'
>     nvsize=8
>     Off_t='off_t'
>     lseeksize=8
>     alignbytes=8
>     prototype=define
>   Linker and Libraries:
>     ld='cc'
>     ldflags =' -fstack-protector-strong -L/usr/local/lib'
>     libpth=/usr/local/lib /usr/lib/gcc/x86_64-linux-gnu/7/include-
> fixed /usr/include/x86_64-linux-gnu /usr/lib /lib/x86_64-linux-gnu
> /lib/../lib /usr/lib/x86_64-linux-gnu /usr/lib/../lib /lib
>     libs=-lpthread -lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc
> -lgdbm_compat
>     perllibs=-lpthread -lnsl -ldl -lm -lcrypt -lutil -lc
>     libc=libc-2.26.so
>     so=so
>     useshrplib=false
>     libperl=libperl.a
>     gnulibc_version='2.26'
>   Dynamic Linking:
>     dlsrc=dl_dlopen.xs
>     dlext=so
>     d_dlsymun=undef
>     ccdlflags='-Wl,-E'
>     cccdlflags='-fPIC'
>     lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector-strong'
> 
> Locally applied patches:
>     uncommitted-changes
> 
> ---
> @INC for perl 5.27.6:
>     lib
>     /home/cwhitener/.perlbrew/libs/perl-
> 5.26.1@normal/lib/perl5/x86_64-linux
>     /home/cwhitener/.perlbrew/libs/perl-5.26.1@normal/lib/perl5
>     /usr/local/lib/perl5/site_perl/5.27.6/x86_64-linux
>     /usr/local/lib/perl5/site_perl/5.27.6
>     /usr/local/lib/perl5/5.27.6/x86_64-linux
>     /usr/local/lib/perl5/5.27.6
> 
> ---
> Environment for perl 5.27.6:
>     HOME=/home/cwhitener
>     LANG=en_US.UTF-8
>     LANGUAGE (unset)
>     LD_LIBRARY_PATH (unset)
>     LOGDIR (unset)
>     PATH=/home/cwhitener/.perlbrew/libs/perl-
> 5.26.1@normal/bin:/home/cwhitener/perl5/perlbrew/bin:/home/cwhitener/perl5/perlbrew/perls/perl-
> 5.26.1/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
>     PERL5LIB=/home/cwhitener/.perlbrew/libs/perl-
> 5.26.1@normal/lib/perl5
>     PERLBREW_BASHRC_VERSION=0.78
>     PERLBREW_HOME=/home/cwhitener/.perlbrew
>     PERLBREW_LIB=normal
>     PERLBREW_MANPATH=/home/cwhitener/.perlbrew/libs/perl-
> 5.26.1@normal/man:/home/cwhitener/perl5/perlbrew/perls/perl-5.26.1/man
>     PERLBREW_PATH=/home/cwhitener/.perlbrew/libs/perl-
> 5.26.1@normal/bin:/home/cwhitener/perl5/perlbrew/bin:/home/cwhitener/perl5/perlbrew/perls/perl-
> 5.26.1/bin
>     PERLBREW_PERL=perl-5.26.1
>     PERLBREW_ROOT=/home/cwhitener/perl5/perlbrew
>     PERLBREW_VERSION=0.78
>     PERL_BADLANG (unset)
>     PERL_LOCAL_LIB_ROOT=/home/cwhitener/.perlbrew/libs/perl-
> 5.26.1@normal
>     PERL_MB_OPT=--install_base /home/cwhitener/.perlbrew/libs/perl-
> 5.26.1@normal
>     PERL_MM_OPT=INSTALL_BASE=/home/cwhitener/.perlbrew/libs/perl-
> 5.26.1@normal
>     SHELL=/bin/bash

Thank you very much.

-- 
James E Keenan (jkeenan@cpan.org)

---
via perlbug:  queue: perl5 status: new
https://rt.perl.org/Ticket/Display.html?id=132422

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About