From f22a48f57668c742d35f73252def612fb2e2db4c Mon Sep 17 00:00:00 2001 From: =?utf8?q?Adri=C3=A1n=20Arroyo=20Calle?= Date: Tue, 6 Dec 2022 11:58:26 +0100 Subject: [PATCH] Compatible Doclog docs for library(sockets) --- src/lib/sockets.pl | 47 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 42 insertions(+), 5 deletions(-) diff --git a/src/lib/sockets.pl b/src/lib/sockets.pl index e2b1b723..541c3133 100644 --- a/src/lib/sockets.pl +++ b/src/lib/sockets.pl @@ -1,4 +1,9 @@ - +/** +Predicates for handling network sockets, both as a server and as a client. +As a server, you should open a socket an call socket\_server\_accept/4 to get a stream for each connection. +As a client, you should just open a socket and you will receive a stream. +In both cases, with a stream, you can use the usual predicates to read and write to the stream. +*/ :- module(sockets, [socket_client_open/3, socket_server_open/2, socket_server_accept/4, @@ -7,6 +12,18 @@ :- use_module(library(error)). +%% socket_client_open(+Addr, -Stream, +Options). +% +% Open a socket to a server, returning a stream. Addr must satisfy `Addr = Address:Port`. +% +% The following options are available: +% +% * alias(+Alias): Set an alias to the stream +% * eof_action(+Action): Defined what happens if the end of the stream is reached. Values: `error`, `eof_code` and `reset`. +% * reposition(+Boolean): Specifies whether repositioning is required for the stream. `false` is the default. +% * type(+Type): Type can be `text` or `binary`. Defines the type of the stream, if it's optimized for plain text +% or just binary +% socket_client_open(Addr, Stream, Options) :- ( var(Addr) -> throw(error(instantiation_error, socket_client_open/3)) @@ -27,7 +44,11 @@ socket_client_open(Addr, Stream, Options) :- socket_client_open/3), '$socket_client_open'(Address, Port, Stream, Alias, EOFAction, Reposition, Type). - +%% socket_server_open(+Addr, -ServerSocket). +% +% Open a server socket, returning a ServerSocket. Use that ServerSocket to accept incoming connections in +% socket\_server\_accept/4. Addr must satisfy `Addr = Address:Port`. Depending on the operating system +% configuration, some ports might be reserved for superusers. socket_server_open(Addr, ServerSocket) :- must_be(var, ServerSocket), ( ( integer(Addr) ; var(Addr) ) -> @@ -39,7 +60,19 @@ socket_server_open(Addr, ServerSocket) :- '$socket_server_open'(Address, Port, ServerSocket) ). - +%% socket_server_accept(+ServerSocket, -Client, -Stream, +Options). +% +% Given a ServerSocket and a list of Options, accepts a incoming connection, returning data from the Client and +% a Stream to read or write data. +% +% The following options are available: +% +% * alias(+Alias): Set an alias to the stream +% * eof_action(+Action): Defined what happens if the end of the stream is reached. Values: `error`, `eof_code` and `reset`. +% * reposition(+Boolean): Specifies whether repositioning is required for the stream. `false` is the default. +% * type(+Type): Type can be `text` or `binary`. Defines the type of the stream, if it's optimized for plain text +% or just binary +% socket_server_accept(ServerSocket, Client, Stream, Options) :- must_be(var, Client), must_be(var, Stream), @@ -48,10 +81,14 @@ socket_server_accept(ServerSocket, Client, Stream, Options) :- socket_server_accept/4), '$socket_server_accept'(ServerSocket, Client, Stream, Alias, EOFAction, Reposition, Type). - +%% socket_server_close(+ServerSocket). +% +% Stops listening on that ServerSocket. It's recommended to always close a ServerSocket once it's no longer needed socket_server_close(ServerSocket) :- '$socket_server_close'(ServerSocket). - +%% current_hostname(-HostName). +% +% Returns the current hostname of the computer in which Scryer Prolog is executing right now current_hostname(HostName) :- '$current_hostname'(HostName). -- 2.54.0