indexing
	description: "A medium poller for asynchronous IO on IO_MEDIUMs"
	status: "See notice at end of class"
	date: "$Date$"
	revision: "$Revision$"

class interface
	MEDIUM_POLLER

create 

	make
			-- Create poller for multi-event polling.

	make_read_only
			-- Create poller for read events only.

	make_write_only
			-- Create poller for write events only.

	make_exception_only
			-- Create poller for exception events only.

feature -- Initialization

	make
			-- Create poller for multi-event polling.

	make_exception_only
			-- Create poller for exception events only.

	make_read_only
			-- Create poller for read events only.

	make_write_only
			-- Create poller for write events only.
	
feature -- Status report

	address_in_use: BOOLEAN
			-- Address is in use by another socket.
			-- (from SOCKET_RESOURCES)

	address_not_readable: BOOLEAN
			-- Unreadable address
			-- (from SOCKET_RESOURCES)

	already_bound: BOOLEAN
			-- Socket has already been bound.
			-- (from SOCKET_RESOURCES)

	bad_socket_handle: BOOLEAN
			-- Socket descriptor is bad.
			-- (from SOCKET_RESOURCES)

	connect_in_progress: BOOLEAN
			-- Call to connect returned on a non-blocking socket.
			-- (from SOCKET_RESOURCES)

	connection_refused: BOOLEAN
			-- Connection is refused (possibly due to security).
			-- (from SOCKET_RESOURCES)

	dtable_full: BOOLEAN
			-- Descriptor table is full
			-- (from SOCKET_RESOURCES)

	error: STRING
			-- Output a related error message.
			-- (from SOCKET_RESOURCES)

	error_number: INTEGER
			-- Returned error number
			-- (from SOCKET_RESOURCES)

	expired_socket: BOOLEAN
			-- Socket connection has expired.
			-- (from SOCKET_RESOURCES)

	invalid_address: BOOLEAN
			-- Address is not valid.
			-- (from SOCKET_RESOURCES)

	invalid_socket_handle: BOOLEAN
			-- Socket descriptor is not valid.
			-- (from SOCKET_RESOURCES)

	network: BOOLEAN
			-- Socket failed due to network problems.
			-- (from SOCKET_RESOURCES)

	no_buffers: BOOLEAN
			-- No more buffers available
			-- (from SOCKET_RESOURCES)

	no_permission: BOOLEAN
			-- No permission is given to user for this socket.
			-- (from SOCKET_RESOURCES)

	not_connected: BOOLEAN
			-- Socket is not connect.
			-- (from SOCKET_RESOURCES)

	protected_address: BOOLEAN
			-- No access to this address is allowed.
			-- (from SOCKET_RESOURCES)

	protocol_not_supported: BOOLEAN
			-- Protocol is not supported on this platform.
			-- (from SOCKET_RESOURCES)

	socket_family_not_supported: BOOLEAN
			-- Requested family is not supported.
			-- (from SOCKET_RESOURCES)

	socket_in_use: BOOLEAN
			-- Socket is already in use.
			-- (from SOCKET_RESOURCES)

	socket_ok: BOOLEAN
			-- No error
			-- (from SOCKET_RESOURCES)

	socket_would_block: BOOLEAN
			-- Call to read, write, etc would have blocked.
			-- (from SOCKET_RESOURCES)

	zero_option: BOOLEAN
			-- No options provided
			-- (from SOCKET_RESOURCES)
	
feature 

	execute (max_des, time_out_msec: INTEGER)
			-- Poll io_medium's whose descriptor is less than
			-- max_des and process ready media.
			-- If no medium is ready, wait the 'time_out..'
			-- time before returning.
		require
			valid_number: max_des > 0

	medium_select (number_to_check, time_out_msec: INTEGER): INTEGER
			-- Check the multiplexing masks for the
			-- read, write, and exception medium reception
			-- and return the number of mediums waiting
			-- after 'time_out...' time
	
feature --  blocking features

	set_wait
			-- Set poller to block.
		ensure
			wait_set: wait

	unset_wait
			-- Set poller to return after timeout.
		ensure
			wait_not_set: not wait

	wait: BOOLEAN
			-- Poller blocks until event?
			-- (otherwise, returns after timeout)
	
feature -- Externals: flags for send, sendto recv and recvfrom socket calls

	c_msgdontroute: INTEGER
			-- Do not route message
			-- (from SOCKET_RESOURCES)

	c_oobmsg: INTEGER
			-- Out of bound message
			-- (from SOCKET_RESOURCES)

	c_peekmsg: INTEGER
			-- Peek message
			-- (from SOCKET_RESOURCES)
	
feature -- booleans to decide whether to include each mask in the select call

	ignore_exception: BOOLEAN
			-- Is Exception mask ignored?

	ignore_read: BOOLEAN
			-- Is read mask ignored?

	ignore_write: BOOLEAN
			-- Is write mask ignored?

	set_exception
			-- Set exception mask to be looked up.
		ensure
			exception_used: not ignore_exception

	set_ignore_exception
			--  Ignore exception mask.
		ensure
			exception_not_used: ignore_exception

	set_ignore_read
			-- Ignore read mask.
		ensure
			read_not_used: ignore_read

	set_ignore_write
			-- Ignore write mask.
		ensure
			write_not_used: ignore_write

	set_read
			-- Set read mask to be looked up.
		ensure
			read_used: not ignore_read

	set_write
			-- Set write mask to be looked up.
		ensure
			write_used: not ignore_write
	
feature -- commands to be executed

	exception_command_list: ARRAY [POLL_COMMAND]
			-- List of poll commands to be called
			-- when their medium is selected for exception event.

	put_exception_command (a_command: POLL_COMMAND)
			-- Set a_command to be called when exception event
			-- is selected on its io_medium.
		require
			valid_command: a_command /= void
			not_empty_medium: a_command.active_medium /= void
		ensure
			command_added: exception_command_list.has (a_command)

	put_read_command (a_command: POLL_COMMAND)
			-- Set a_command to be called when read event is
			-- selected on its io_medium.
		require
			valid_command: a_command /= void
			not_empty_medium: a_command.active_medium /= void
		ensure
			command_added: read_command_list.has (a_command)

	put_write_command (a_command: POLL_COMMAND)
			-- Set a_command to be called when write event is
			-- selected on its io_medium.
		require
			valid_command: a_command /= void
			not_empty_medium: a_command.active_medium /= void
		ensure
			command_added: write_command_list.has (a_command)

	read_command_list: ARRAY [POLL_COMMAND]
			-- List of poll commands to be called
			-- when their medium is selected for read event.

	remove_associated_exception_command (s: IO_MEDIUM)
			-- Remove command associated with medium s from
			-- exception registered media.
		require
			has_command: exception_command_list.upper >= s.handle
		ensure
			command_removed: exception_command_list.item (s.handle) = void

	remove_associated_read_command (s: IO_MEDIUM)
			-- Remove command associated with medium s from
			-- read registered media.
		require
			has_command: read_command_list.upper >= s.handle
		ensure
			command_removed: read_command_list.item (s.handle) = void

	remove_associated_write_command (s: IO_MEDIUM)
			-- Remove command associated with medium s from
			-- write registered media.
		require
			has_command: write_command_list.upper >= s.handle
		ensure
			command_removed: write_command_list.item (s.handle) = void

	remove_exception_command (a_command: POLL_COMMAND)
			-- Remove a_command from exception registered media.
		require
			has_command: exception_command_list.has (a_command)
		ensure
			command_removed: not exception_command_list.has (a_command)

	remove_read_command (a_command: POLL_COMMAND)
			-- Remove a_command from read registered media.
		require
			valid_command: a_command /= void
			has_command: read_command_list.has (a_command)
			not_empty_medium: a_command.active_medium /= void
		ensure
			command_removed: not read_command_list.has (a_command)

	remove_write_command (a_command: POLL_COMMAND)
			-- Remove a_command from write registered media.
		require
			has_command: write_command_list.has (a_command)
		ensure
			command_removed: not write_command_list.has (a_command)

	write_command_list: ARRAY [POLL_COMMAND]
			-- List of poll commands to be called
			-- when their medium is selected for write event.
	
feature -- medium masks

	except_mask: POLL_MASK
			-- Exception mask used by medium select

	last_except_mask: POLL_MASK
			-- Exception mask returned by medium select

	last_read_mask: POLL_MASK
			-- Read mask returned by medium select

	last_write_mask: POLL_MASK
			-- Write mask returned by medium select

	read_mask: POLL_MASK
			-- Read mask used by medium select

	write_mask: POLL_MASK
			-- Write mask used by medium select.
	
feature -- process set commands

	process_selected (number_of_selected: INTEGER)
			-- Process commands for ready media.
		require
			valid_number: number_of_selected > 0
	
invariant

		-- from ANY
	reflexive_equality: standard_is_equal (Current)
	reflexive_conformance: conforms_to (Current)

end -- class MEDIUM_POLLER