Types

class quanser.common.types.Timeout(seconds=0, nanoseconds=0, is_absolute=False)

A class for dealing with timeouts. Note that Timeouts support addition and subtraction, as well as comparisons There are also a number of class methods for creating Timeouts and three read-only properties: seconds, nanoseconds and is_absolute.

Parameters

seconds (int) – The seconds portion of the timeout.
nanoseconds (int) – The nanoseconds portion of the timeout.
is_absolute (boolean) – Indicates whether the timeout is a relative timeout or an absolute timeout.

Examples

Create a 20-second timeout

>>> from quanser.common import Timeout
>>> timeout = Timeout(20)

Create a 2000-nanosecond timeout

>>> from quanser.common import Timeout
>>> timeout = Timeout(nanoseconds = 2000)

Create a 1.02 second absolute timeout

>>> from quanser.common import Timeout
>>> timeout = Timeout(1, 20000000, True)

classmethod Timeout.get_timeout(interval)

Get a relative Timeout instance from a time interval in seconds (including fractional seconds). A negative interval will result in a zero Timeout.

Parameters: interval (float) – A non-negative time interval in seconds (including fractional seconds) to be represented by the Timeout instance.
Returns: timeout – The relative Timeout instance representing the same number of seconds (including fractional seconds)
Return type: Timeout

Example

Creating a relative Timeout of 1.5 seconds:

>>> timeout = Timeout.get_timeout(1.5)

classmethod Timeout.get_current_time()

Get the current time as an absolute Timeout instance. On some platforms, this function may not return as much resolution as Timeout.get_high_resolution_time().

Raises: GenericError – An exception is raised if the current time cannot be obtained.
Returns: timeout – An absolute Timeout instance representing the current time.
Return type: Timeout

Example

Getting the current time:

>>> timeout = Timeout.get_current_time()

classmethod Timeout.get_high_resolution_time()

Get the current time as an absolute Timeout instance with the highest resolution. On some platforms, this method may be more expensive than Timeout.get_current_time().

Raises: GenericError – An exception is raised if the current high-resolution time cannot be obtained.
Returns: timeout – An absolute Timeout instance representing the current time with the highest resolution.
Return type: Timeout

Example

Getting the current time as a high-resolution time:

>>> timeout = Timeout.get_high_resolution_time()

classmethod Timeout.get_thread_cpu_time()

Get the current thread CPU time as a relative Timeout instance.

Raises: GenericError – An exception is raised if the thread CPU time cannot be obtained.
Returns: timeout – A relative Timeout instance representing the current thread CPU time.
Return type: Timeout

Example

Getting the current thread CPU time:

>>> timeout = Timeout.get_thread_cpu_time()

classmethod Timeout.get_process_cpu_time()

Get the current process CPU time as a relative Timeout instance.

Raises: GenericError – An exception is raised if the process CPU time cannot be obtained.
Returns: timeout – A relative Timeout instance representing the current process CPU time.
Return type: Timeout

Example

Getting the current process CPU time:

>>> timeout = Timeout.get_process_cpu_time()

property Timeout.seconds

Get the number of seconds stored in the Timeout instance.

Example

Get the seconds portion of the Timeout.

>>> timeout = Timeout.get_timeout(2.5)
>>> secs = timeout.seconds    # secs = 2

property Timeout.nanoseconds

Get the number of nanoseconds stored in the Timeout instance.

Example

Get the nanoseconds portion of the Timeout.

>>> timeout = Timeout.get_timeout(2.5)
>>> nsecs = timeout.nanoseconds    # nsecs = 500000000

property Timeout.is_absolute

Determine whether the Timeout is absolute or relative.

Example

See if the Timeout is absolute or not:

>>> timeout = Timeout.get_timeout(2.5)
>>> absolute = timeout.is_absolute    # absolute = False

Timeout.set_current_time()

Set the value of this Timeout instance to the current time as an absolute Timeout. On some platforms, this function may not return as much resolution as Timeout.set_high_resolution_time().

Raises: GenericError – An exception is raised if the current time cannot be obtained.

Example

Setting the current time:

>>> timeout = Timeout()
>>> timeout.set_current_time()

Timeout.set_high_resolution_time()

Set the value of this Timeout instance as a relative Timeout representing the current time with the highest resolution. On some platforms, this method may be more expensive than Timeout.set_current_time().

Raises: GenericError – An exception is raised if the current high-resolution time cannot be obtained.

Example

Setting the current time as a high-resolution time:

>>> timeout = Timeout()
>>> timeout.get_high_resolution_time()

Timeout.set_thread_cpu_time()

Set the value of this Timeout as a relative Timeout respresenting the current thread CPU time.

Raises: GenericError – An exception is raised if the thread CPU time cannot be obtained.

Example

Setting the current thread CPU time:

>>> timeout = Timeout()
>>> timeout.get_thread_cpu_time()

Timeout.set_process_cpu_time()

Set the value of this Timeout as a relative Timeout respresenting the current process CPU time.

Raises: GenericError – An exception is raised if the process CPU time cannot be obtained.

Example

Setting the current process CPU time:

>>> timeout = Timeout()
>>> timeout.get_process_cpu_time()

Timeout.is_negative()

Indicates whether the Timeout is negative or not.

Example

See if the Timeout is negative or not:

>>> timeout = Timeout.get_timeout(-2)
>>> neg = timeout.is_negative()    # neg = True

Timeout.is_zero()

Indicates whether the Timeout is zero or not.

Example

See if the Timeout is zero or not:

>>> timeout = Timeout()
>>> zero = timeout.is_zero()    # zero = True

Timeout.is_expired()

Indicates whether the Timeout has already expired. Absolute timeouts are compared to the current time. Relative timeouts are expired if they are negative or zero.

Example

See if the Timeout has expired or not:

>>> timeout = Timeout.get_current_time()
>>> relative = Timeout(1)
>>> timeout += relative
>>> expired = timeout.is_expired()    # expired = False

Timeout.compare(rhs)

Compares two Timeouts and returns -1 if the left-hand side is less than the right-hand side, zero if the two Timeouts are equal and +1 if the left-hand side is greater than the rigt-hand side.

Raises: GenericError – An exception is raised if the comparison cannot be performed.

Example

Compares two Timeouts:

>>> timeout = Timeout.get_current_time()
>>> interval = Timeout(5)
>>> other_timeout = timeout + interval
>>> cmp = timeout.compare(other_timeout) # cmp = -1

Timeout.get_absolute()

Gets an absolute Timeout from the given relative Timeout.

Raises: GenericError – An exception is raised if the conversion cannot be performed.

Example

Get the absolute time five seconds from now:

>>> timeout = Timeout(5)
>>> abs_timeout = timeout.get_absolute()

Timeout.get_relative()

Gets a relative Timeout from the given absolute Timeout.

Raises: GenericError – An exception is raised if the conversion cannot be performed.

Example

Get the relative time from the given absolute Timeout to the current time:

>>> rel_timeout = abs_timeout.get_relative()

Timeout.get_milliseconds()

Returns the total number of milliseconds represented by the Timeout as an integer.

Raises: GenericError – An exception is raised if the number of milliseconds cannot be determined.

Example

Get the total number of milliseconds represented by the Timeout:

>>> timeout = Timeout.get_timeout(1.5)
>>> ms = timeout.get_milliseconds() # ms = 1500

Timeout.__add__(rhs)

Adds one Timeout to another as the addition operator.

Raises: GenericError – An exception is raised if the subtraction cannot be performed.

Example

Add five seconds to the current time.

>>> start = Timeout.get_current_time()
>>> interval = Timeout(5)
>>> stop = start + interval

Timeout.__iadd__(rhs)

Adds one Timeout to another in-place as the += operator.

Raises: GenericError – An exception is raised if the subtraction cannot be performed.

Example

Add five seconds to the current time.

>>> stop = Timeout.get_current_time()
>>> interval = Timeout(5)
>>> stop += interval

Timeout.__sub__(rhs)

Subtracts one Timeout from another as the subtraction operator.

Raises: GenericError – An exception is raised if the subtraction cannot be performed.

Example

Get the time between two absolute Timeouts:

>>> start = Timeout.get_current_time()
>>> ...
>>> stop = Timeout.get_current_time()
>>> elapsed = stop - start

Timeout.__isub__(rhs)

Subtracts one Timeout from another in-place as the -= operator.

Raises: GenericError – An exception is raised if the subtraction cannot be performed.

Example

Get the time between two absolute Timeouts:

>>> start = Timeout.get_current_time()
>>> ...
>>> elapsed = Timeout.get_current_time()
>>> elapsed -= start

Timeout.__eq__(rhs)

Compares two Timeouts for equality.

Raises: GenericError – An exception is raised if the subtraction cannot be performed.

Example

Compare two Timeouts:

>>> start = Timeout.get_current_time()
>>> stop = Timeout.get_current_time()
>>> same = (start == stop)

Timeout.__lt__(rhs)

Implements the less-than operator.

Raises: GenericError – An exception is raised if the subtraction cannot be performed.

Example

Compare two Timeouts:

>>> start = Timeout.get_current_time()
>>> stop = Timeout.get_current_time()
>>> same = (start < stop)

Timeout.__le__(rhs)

Implements the less-than or equal-to operator.

Raises: GenericError – An exception is raised if the subtraction cannot be performed.

Example

Compare two Timeouts:

>>> start = Timeout.get_current_time()
>>> stop = Timeout.get_current_time()
>>> same = (start <= stop)

Timeout.__ge__(rhs)

Implements the greater-than or equal-to operator.

Raises: GenericError – An exception is raised if the subtraction cannot be performed.

Example

Compare two Timeouts:

>>> start = Timeout.get_current_time()
>>> stop = Timeout.get_current_time()
>>> same = (start >= stop)

Timeout.__gt__(rhs)

Implements the greater-than operator.

Raises: GenericError – An exception is raised if the subtraction cannot be performed.

Example

Compare two Timeouts:

>>> start = Timeout.get_current_time()
>>> stop = Timeout.get_current_time()
>>> same = (start > stop)