opsys_ifc.sa
Generated by gen_html_sa_files from ICSI. Contact gomes@icsi.berkeley.edu for details
-------------------------> GNU Sather - sourcefile <-------------------------
-- Copyright (C) 2000 by K Hopper, University of Waikato, New Zealand --
-- This file is part of the GNU Sather library. It is free software; you may --
-- redistribute and/or modify it under the terms of the GNU Library General --
-- Public License (LGPL) as published by the Free Software Foundation; --
-- either version 2 of the license, or (at your option) any later version. --
-- This library is distributed in the hope that it will be useful, but --
-- WITHOUT ANY WARRANTY without even the implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE. See Doc/LGPL for more details. --
-- The license text is also available from: Free Software Foundation, Inc., --
-- 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA --
--------------> Please email comments to <bug-sather@gnu.org> <--------------
abstract class $OPERATING_SYS
abstract class $OPERATING_SYS is
-- This class models only those functions necessary to provide an
-- interface to the underlying operating system by a Sather program using
-- only the standard library. This excludes services provided by other
-- interface classes which model specific OS features.
-- Version 1.0 Feb 99. Copyright K Hopper, U of Waikato
-- Development History
-- -------------------
-- Date Who By Detail
-- ---- ------ ------
-- 3 Feb 99 kh Original
system(
cli_cmd : STR
) : CARD ;
-- This routine provides a service to invoke an OS-dependent command
-- line interpreter. The returned value is zero if successful, otherwise
-- an OS-dependent number indicating in an OS-dependent manner what caused
-- the failure.
get_env(
var_name : STR
) : STR ;
-- This routine returns the value of the environment variable named in
-- the parameter, if it exists, otherwise void.
resource_location(
lib : LIBCHARS
) : STR ;
-- This routine returns an encoding of the dynamic resource path for
-- all Sather libraries, the first element of which is expected to be
-- the standard language library.
exec(
prog_name : STR,
argv : ARRAY{STR},
envp : ARRAY{STR}
) : CARD ;
-- This routine expects its first argument to be the full path name of
-- an executable file. The program contained is then invoked, passing to it
-- the second and third parameters as program arguments and environment
-- variables respectively. If this routine returns then an error will have
-- occurred. The value returned will be some operating system dependent
-- error reason code.
exit(
code : INT
) ;
-- This routine performs operating system dependent termination action,
-- which may include passing 'code' to the invoking thread/process.
abort ;
-- This routine performs the OS-dependent actions associated with
-- stopping program execution as quickly as possible.
end ; -- $OPERATING_SYS
abstract class $OPSYS_TIME
abstract class $OPSYS_TIME is
-- This class models the concept of a clock/calendar time. It is likely
-- that a particular operating system implementation will contain additional
-- routines which are not, therefore, portable.
-- Version 1.0 Feb 99. Copyright K Hopper, U of Waikato
-- Development History
-- -------------------
-- Date Who By Detail
-- ---- ------ ------
-- 3 Feb 99 kh Original
Base_Year : CARD ;
-- This feature is expected to be a constant giving the year from
-- the beginning of which all operating system time-of-day clock measurements
-- are made.
days : CARD ;
-- This contains the whole number of days after the base date which is
-- represented by self.
millisecs : CARD ;
-- This contains the number of miiliseconds which have so far elapsed
-- from the beginning of the current day.
-- The following group of features, expected to be constants in practice,
-- are useful when manipulating times/days.
Hours_per_Day : CARD ;
Mins_per_Hour : CARD ;
Seconds_per_Min : CARD ;
Millisecs_per_Second : CARD ;
Seconds_per_Day : CARD ;
Ticks_per_Day : CARD ;
Ticks_per_Second : CARD ;
Ticks_per_Millisec : CARD ;
read_possible : BOOL ;
-- This function returns TRUE iff it is possible to obtain time/date
-- information from a system clock, otherwise FALSE.
set_possible : BOOL ;
-- This predicate returns true if and only if it is possible for this
-- program to set or adjust the time of the system time/date clock.
create(
day : CARD,
millisecs : CARD
) : SAME ;
-- This routine takes the given day and millisecs, returning an operating
-- system dependent equivalent clock time.
create(
ticks : CARD
) : SAME ;
-- This routine takes the given number of ticks which has been returned
-- from calls to ?? and ??, returning an operating system dependent
-- equivalent clock time.
time_stamp : SAME ;
-- This procedure returns the current date/time as known by the
-- system clock. The date/time returned depends upon the setting of the
-- clock - and may be void if some system problem occurred!
adjust_clock(
offset : INT -- in ticks!
) : BOOL ;
-- This routine returns true if and only if it has been possible to
-- alter the value of the system clock by the given number of milliseconds,
-- otherwise false -- due to a failure in setting.
count : CARD ;
-- This routine converts the time-stamp to an Operating System specific
-- count of ticks.
end ; -- $OPSYS_TIME
abstract class $OPSYS_TIME_USAGE < $STR
abstract class $OPSYS_TIME_USAGE < $STR is
-- This class models the operating system specific system processor
-- times. The exact values of these times depend solely on the underlying
-- operating system and may be different under identical circumstances on
-- different systems.
-- Implementations will frequently offer additional facilities to
-- interrogate individual components (if any) of the operating system values.
-- USE AT YOUR OWN RISK!!!
-- Version 1.0 Feb 99. Copyright K Hopper, U of Waikato
-- Development History
-- -------------------
-- Date Who By Detail
-- ---- ------ ------
-- 3 Feb 99 kh Original
wall_time : CARD ;
-- Wall time (from the real-time clock) in clock ticks.
create : SAME ;
-- This routine creates a time-stamp consisting of the built in process
-- time facility. The count set into wall_time is the implementation-
-- defined ticks since some base date (ie not an absolute time).
now ;
-- This routine is the operating system 'processor time now' service.
-- If this fails then nothing can be done but raise an exception for the
-- program to handle!
start ;
-- This routine which may be used to determine some interval start time
-- is merely a renaming of the one above.
elapsed : CARD ;
-- This routine returns the time in clock ticks elapsed since the most
-- recent call of start (or now).
plus(
other : SAME
) : SAME ;
-- This routine returns the result of adding the two times self and
-- other. Note that the result is given a new time-stamp indicating when
-- the calculation was done, since adding two wall-times is meaningless.
minus(
other : SAME
) : SAME ;
-- This routine only provides a meaningful result if all of the component
-- values in self are greater than or equal to the corresponding component in
-- other!
end ; -- $OPSYS_TIME_USAGE
abstract class $OPSYS_MEMORY_USAGE < $STR
abstract class $OPSYS_MEMORY_USAGE < $STR is
-- This class models the memory usage abstraction for a program --
-- given the underlying operating system facilities.
-- Note that this service will in general be built in to either or both
-- of the compilation system and/or garbage collector.
-- Version 1.1 Oct 98. Copyright K Hopper, U of Waikato
-- Development History
-- -------------------
-- Date Who By Detail
-- ---- ------ ------
-- 15 Apr 97 kh Original from distribution library
-- 15 Oct 98 kh Revised and added pre/post conditions
now ;
-- This is the routine built-in to this implementation which determines
-- current memory size details.
start ;
-- This routine is a renaming of the above routine.
used : SAME ;
-- This routine returns the amount of memory used since the last call
-- of start.
plus(
other : SAME
) : SAME ;
-- This routine returns the sum of self and other.
minus(
other : SAME
) : SAME ;
-- This routine returns the difference between self and other.
end ; -- $OPSYS MEMORY_USAGE
abstract class $OPSYS_TIMERS
abstract class $OPSYS_TIMERS is
-- This class identifies all of the timers available to a program from
-- the underlying operating system. In practice it is expected to be an
-- enumeration which will frequently contain additional timers available from
-- a particular operating system implementation.
-- Version 1.0 Feb 99. Copyright K Hopper, U of Waikato
-- Development History
-- -------------------
-- Date Who By Detail
-- ---- ------ ------
-- 3 Feb 99 kh Original
Default : $OPSYS_TIMER ;
Virtual : $OPSYS_TIMER ;
end ; -- $OPSYS_TIMERS
abstract class $OPSYS_TIMER
abstract class $OPSYS_TIMER is
-- This class models the concept of an operating system/processor
-- timer of some kind which counts up or down in ticks as set by the program.
-- A timer may be set to issue an alarm call if appropriate -- when a handler
-- (if provided) will be invoked.
-- Version 1.0 Feb 99. Copyright K Hopper, U of Waikato
-- Development History
-- -------------------
-- Date Who By Detail
-- ---- ------ ------
-- 3 Feb 99 kh Original
create(
which : $OPSYS_TIMERS
) : SAME ;
-- This routine attempts to create a program timer for the indicated
-- operating system timer. If unsuccessful then void is returned.
exists(
which : $OPSYS_TIMERS
) : BOOL ;
-- This predicate returns true if and only if there is an existing
-- program timer connected to the indicated timer.
set_count(
which : $OPSYS_TIMERS,
delay : CARD
) : BOOL ;
-- This routine returns true if and only if it has been possible to set
-- the indicated timer to provide a delay of the given number of clock ticks,
-- otherwise false.
set_alarm(
clock_time : $OPSYS_TIME,
handler : ROUT{$OPSYS_TIMERS} : BOOL
) : BOOL ;
-- This routine sets the indicated timer to expire at the given clock
-- time and attaches the handler provided to be called when the time is
-- reached, returning true only if this has been done successfully -- or if
-- the clock time has already passed, otherwise false. If the handler is
-- void then nothing is done when the time is reached.
repeat_alarm(
delay : $OPSYS_TIME,
handler : ROUT{$OPSYS_TIMERS} : BOOL
) : BOOL ;
-- This routine sets the indicated timer to expire after the given
-- delay and attaches the handler provided to be called each time that
-- the count expires -- when the count commences again (unless altered within
-- the handler, returning true only if this has been done successfully,
-- otherwise false.
read : $OPSYS_TIME ;
-- This routine returns the time at which the given timer is expected to
-- reach the count specified. If the timer has already reached its expiry
-- time then void is returned.
reset : CARD ;
-- This routine resets the indicated timer to its original delay.
-- Any time remaining on the counter is returned in milliseconds. If an alarm
-- handler has been established then it is NOT cleared.
new_handler(
handler : ROUT{$OPSYS_TIMERS} : BOOL
) : BOOL ;
-- This routine enables the using class to atomically change the handler
-- for the indicated timer to the new routine value (which may be void in
-- which case the action for that signal is set to ignore).
cancel : CARD ;
-- This routine cancels the current count on the indicated timer,
-- stops the timer and then returns the number of ticks remaining at the
-- instant of cancellation. Any signal handler is removed from the
-- appropriate alarm which is set to default handling!
destroy ;
-- This routine deletes any outstanding count, clears the timer and
-- cancels the validity of this object.
end ; -- $OPSYS_TIMER