-- --
-- S p e c --
-- --
--- Copyright (C) 2001-2009, AdaCore --
+-- Copyright (C) 2001-2010, AdaCore --
-- --
-- GNAT is free software; you can redistribute it and/or modify it under --
-- terms of the GNU General Public License as published by the Free Soft- --
type Selector_Access is access all Selector_Type;
-- Selector objects are used to wait for i/o events to occur on sockets
+ Null_Selector : constant Selector_Type;
+ -- The Null_Selector can be used in place of a normal selector without
+ -- having to call Create_Selector if the use of Abort_Selector is not
+ -- required.
+
-- Timeval_Duration is a subtype of Standard.Duration because the full
-- range of Standard.Duration cannot be represented in the equivalent C
-- structure. Moreover, negative values are not allowed to avoid system
type Family_Type is (Family_Inet, Family_Inet6);
-- Address family (or protocol family) identifies the communication domain
- -- and groups protocols with similar address formats. IPv6 will soon be
- -- supported.
+ -- and groups protocols with similar address formats.
type Mode_Type is (Socket_Stream, Socket_Datagram);
-- Stream sockets provide connection-oriented byte streams. Datagram
-- more data can be transmitted. Neither transmission nor reception can be
-- performed with Shut_Read_Write.
- type Port_Type is new Natural;
- -- Classical port definition. No_Port provides a special value to
- -- denote uninitialized port. Any_Port provides a special value
- -- enabling all ports.
+ type Port_Type is range 0 .. 16#ffff#;
+ -- TCP/UDP port number
Any_Port : constant Port_Type;
- No_Port : constant Port_Type;
+ -- All ports
+
+ No_Port : constant Port_Type;
+ -- Uninitialized port number
type Inet_Addr_Type (Family : Family_Type := Family_Inet) is private;
-- An Internet address depends on an address family (IPv4 contains 4 octets
-- with a socket. Options may exist at multiple protocol levels in the
-- communication stack. Socket_Level is the uppermost socket level.
- type Level_Type is (
- Socket_Level,
- IP_Protocol_For_IP_Level,
- IP_Protocol_For_UDP_Level,
- IP_Protocol_For_TCP_Level);
+ type Level_Type is
+ (Socket_Level,
+ IP_Protocol_For_IP_Level,
+ IP_Protocol_For_UDP_Level,
+ IP_Protocol_For_TCP_Level);
-- There are several options available to manipulate sockets. Each option
-- has a name and several values available. Most of the time, the value is
-- a boolean to enable or disable this option.
- type Option_Name is (
- Keep_Alive, -- Enable sending of keep-alive messages
- Reuse_Address, -- Allow bind to reuse local address
- Broadcast, -- Enable datagram sockets to recv/send broadcasts
- Send_Buffer, -- Set/get the maximum socket send buffer in bytes
- Receive_Buffer, -- Set/get the maximum socket recv buffer in bytes
- Linger, -- Shutdown wait for msg to be sent or timeout occur
- Error, -- Get and clear the pending socket error
- No_Delay, -- Do not delay send to coalesce data (TCP_NODELAY)
- Add_Membership, -- Join a multicast group
- Drop_Membership, -- Leave a multicast group
- Multicast_If, -- Set default out interface for multicast packets
- Multicast_TTL, -- Set the time-to-live of sent multicast packets
- Multicast_Loop, -- Sent multicast packets are looped to local socket
- Receive_Packet_Info, -- Receive low level packet info as ancillary data
- Send_Timeout, -- Set timeout value for output
- Receive_Timeout); -- Set timeout value for input
+ type Option_Name is
+ (Keep_Alive, -- Enable sending of keep-alive messages
+ Reuse_Address, -- Allow bind to reuse local address
+ Broadcast, -- Enable datagram sockets to recv/send broadcasts
+ Send_Buffer, -- Set/get the maximum socket send buffer in bytes
+ Receive_Buffer, -- Set/get the maximum socket recv buffer in bytes
+ Linger, -- Shutdown wait for msg to be sent or timeout occur
+ Error, -- Get and clear the pending socket error
+ No_Delay, -- Do not delay send to coalesce data (TCP_NODELAY)
+ Add_Membership, -- Join a multicast group
+ Drop_Membership, -- Leave a multicast group
+ Multicast_If, -- Set default out interface for multicast packets
+ Multicast_TTL, -- Set the time-to-live of sent multicast packets
+ Multicast_Loop, -- Sent multicast packets are looped to local socket
+ Receive_Packet_Info, -- Receive low level packet info as ancillary data
+ Send_Timeout, -- Set timeout value for output
+ Receive_Timeout); -- Set timeout value for input
type Option_Type (Name : Option_Name := Keep_Alive) is record
case Name is
-- socket options in that they are not specific to sockets but are
-- available for any device.
- type Request_Name is (
- Non_Blocking_IO, -- Cause a caller not to wait on blocking operations.
+ type Request_Name is
+ (Non_Blocking_IO, -- Cause a caller not to wait on blocking operations
N_Bytes_To_Read); -- Return the number of bytes available to read
type Request_Type (Name : Request_Name := Non_Blocking_IO) is record
Flags : Request_Flag_Type := No_Request_Flag);
-- Receive message from Socket. Last is the index value such that Item
-- (Last) is the last character assigned. Note that Last is set to
- -- Item'First - 1 (or to Stream_Element_Array'Last if Item'First is
- -- Stream_Element_Offset'First) when the socket has been closed by peer.
- -- This is not an error and no exception is raised. Flags allows to
- -- control the reception. Raise Socket_Error on error.
+ -- Item'First - 1 when the socket has been closed by peer. This is not
+ -- an error, and no exception is raised in this case unless Item'First
+ -- is Stream_Element_Offset'First, in which case Constraint_Error is
+ -- raised. Flags allows to control the reception. Raise Socket_Error on
+ -- error.
procedure Receive_Socket
(Socket : Socket_Type;
-- Transmit a message over a socket. For a datagram socket, the address
-- is given by To.all. For a stream socket, To must be null. Last
-- is the index value such that Item (Last) is the last character
- -- sent. Note that Last is set to Item'First - 1 (if Item'First is
- -- Stream_Element_Offset'First, to Stream_Element_Array'Last) when the
- -- socket has been closed by peer. This is not an error and no exception
- -- is raised. Flags allows control of the transmission. Raises exception
- -- Socket_Error on error. Note: this subprogram is inlined because it is
- -- also used to implement the two variants below.
+ -- sent. Note that Last is set to Item'First - 1 if the socket has been
+ -- closed by the peer (unless Item'First is Stream_Element_Offset'First,
+ -- in which case Constraint_Error is raised instead). This is not an error,
+ -- and Socket_Error is not raised in that case. Flags allows control of the
+ -- transmission. Raises exception Socket_Error on error. Note: this
+ -- subprogram is inlined because it is also used to implement the two
+ -- variants below.
procedure Send_Socket
(Socket : Socket_Type;
Count : out Ada.Streams.Stream_Element_Count;
Flags : Request_Flag_Type := No_Request_Flag);
-- Transmit data gathered from the set of vector elements Vector to a
- -- socket. Count is set to the count of transmitted stream elements.
- -- Flags allow control over transmission.
+ -- socket. Count is set to the count of transmitted stream elements. Flags
+ -- allow control over transmission.
procedure Set_Socket_Option
(Socket : Socket_Type;
procedure Shutdown_Socket
(Socket : Socket_Type;
How : Shutmode_Type := Shut_Read_Write);
- -- Shutdown a connected socket. If How is Shut_Read, further receives will
- -- be disallowed. If How is Shut_Write, further sends will be disallowed.
- -- If how is Shut_Read_Write, further sends and receives will be
- -- disallowed.
+ -- Shutdown a connected socket. If How is Shut_Read further receives will
+ -- be disallowed. If How is Shut_Write further sends will be disallowed.
+ -- If How is Shut_Read_Write further sends and receives will be disallowed.
type Stream_Access is access all Ada.Streams.Root_Stream_Type'Class;
-- Same interface as Ada.Streams.Stream_IO
procedure Free is new Ada.Unchecked_Deallocation
(Ada.Streams.Root_Stream_Type'Class, Stream_Access);
- -- Destroy a stream created by one of the Stream functions above,
- -- releasing the corresponding resources. The user is responsible for
- -- calling this subprogram when the stream is not needed anymore.
+ -- Destroy a stream created by one of the Stream functions above, releasing
+ -- the corresponding resources. The user is responsible for calling this
+ -- subprogram when the stream is not needed anymore.
type Socket_Set_Type is limited private;
-- This type allows to manipulate sets of sockets. It allows to wait for
-- can block the full process (not just the calling thread).
--
-- Check_Selector provides the very same behaviour. The only difference is
- -- that it does not watch for exception events. Note that on some
- -- platforms it is kept process blocking on purpose. The timeout parameter
- -- allows the user to have the behaviour he wants. Abort_Selector allows
- -- to safely abort a blocked Check_Selector call. A special socket
- -- is opened by Create_Selector and included in each call to
- -- Check_Selector. Abort_Selector causes an event to occur on this
- -- descriptor in order to unblock Check_Selector. Note that each call to
- -- Abort_Selector will cause exactly one call to Check_Selector to return
- -- with Aborted status. The special socket created by Create_Selector is
- -- closed when Close_Selector is called.
+ -- that it does not watch for exception events. Note that on some platforms
+ -- it is kept process blocking on purpose. The timeout parameter allows the
+ -- user to have the behaviour he wants. Abort_Selector allows to safely
+ -- abort a blocked Check_Selector call. A special socket is opened by
+ -- Create_Selector and included in each call to Check_Selector.
+ --
+ -- Abort_Selector causes an event to occur on this descriptor in order to
+ -- unblock Check_Selector. Note that each call to Abort_Selector will cause
+ -- exactly one call to Check_Selector to return with Aborted status. The
+ -- special socket created by Create_Selector is closed when Close_Selector
+ -- is called.
+ --
-- A typical case where it is useful to abort a Check_Selector operation is
-- the situation where a change to the monitored sockets set must be made.
procedure Create_Selector (Selector : out Selector_Type);
- -- Create a new selector
+ -- Initialize (open) a new selector
procedure Close_Selector (Selector : in out Selector_Type);
-- Close Selector and all internal descriptors associated; deallocate any
-- associated resources. This subprogram may be called only when there is
-- no other task still using Selector (i.e. still executing Check_Selector
- -- or Abort_Selector on this Selector).
+ -- or Abort_Selector on this Selector). Has no effect if Selector is
+ -- already closed.
procedure Check_Selector
- (Selector : in out Selector_Type;
+ (Selector : Selector_Type;
R_Socket_Set : in out Socket_Set_Type;
W_Socket_Set : in out Socket_Set_Type;
Status : out Selector_Status;
-- R_Socket_Set or W_Socket_Set. Status is set to Expired if no socket was
-- ready after a Timeout expiration. Status is set to Aborted if an abort
-- signal has been received while checking socket status.
+ --
-- Note that two different Socket_Set_Type objects must be passed as
-- R_Socket_Set and W_Socket_Set (even if they denote the same set of
-- Sockets), or some event may be lost.
- -- Socket_Error is raised when the select(2) system call returns an
- -- error condition, or when a read error occurs on the signalling socket
- -- used for the implementation of Abort_Selector.
+ --
+ -- Socket_Error is raised when the select(2) system call returns an error
+ -- condition, or when a read error occurs on the signalling socket used for
+ -- the implementation of Abort_Selector.
procedure Check_Selector
- (Selector : in out Selector_Type;
+ (Selector : Selector_Type;
R_Socket_Set : in out Socket_Set_Type;
W_Socket_Set : in out Socket_Set_Type;
E_Socket_Set : in out Socket_Set_Type;
-- different objects.
procedure Abort_Selector (Selector : Selector_Type);
- -- Send an abort signal to the selector
+ -- Send an abort signal to the selector. The Selector may not be the
+ -- Null_Selector.
type Fd_Set is private;
-- ??? This type must not be used directly, it needs to be visible because
type Socket_Type is new Integer;
No_Socket : constant Socket_Type := -1;
- type Selector_Type is limited record
- R_Sig_Socket : Socket_Type := No_Socket;
- W_Sig_Socket : Socket_Type := No_Socket;
- -- Signalling sockets used to abort a select operation
+ -- A selector is either a null selector, which is always "open" and can
+ -- never be aborted, or a regular selector, which is created "closed",
+ -- becomes "open" when Create_Selector is called, and "closed" again when
+ -- Close_Selector is called.
+
+ type Selector_Type (Is_Null : Boolean := False) is limited record
+ case Is_Null is
+ when True =>
+ null;
+
+ when False =>
+ R_Sig_Socket : Socket_Type := No_Socket;
+ W_Sig_Socket : Socket_Type := No_Socket;
+ -- Signalling sockets used to abort a select operation
+
+ end case;
end record;
pragma Volatile (Selector_Type);
+ Null_Selector : constant Selector_Type := (Is_Null => True);
+
type Fd_Set is
new System.Storage_Elements.Storage_Array (1 .. SOSC.SIZEOF_fd_set);
for Fd_Set'Alignment use Interfaces.C.long'Alignment;
-- Highest socket in set. Last = No_Socket denotes an empty set (which
-- is the default initial value).
- Set : aliased Fd_Set;
+ Set : aliased Fd_Set;
-- Underlying socket set. Note that the contents of this component is
-- undefined if Last = No_Socket.
end record;
OSDN Git Service
