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