-! (c)Joe Groff bsd license
-USING: help help.markup help.syntax quotations ;
+! Copyright (C) 2009 Joe Groff.
+! See http://factorcode.org/license.txt for BSD license.
+USING: help.markup help.syntax kernel math.floats.env quotations ;
IN: math.floats.env
HELP: fp-exception
{ $class-description "This symbol represents the non-IEEE-754-compliant flush-denormals-to-zero " { $link fp-denormal-mode } "." } ;
HELP: fp-exception-flags
-{ $values { "exceptions" "a sequence of " { $link fp-exception } " symbols" } }
+{ $values { "exceptions" { $sequence fp-exception } } }
{ $description "Returns the set of floating-point exception flags that have been raised." } ;
HELP: set-fp-exception-flags
-{ $values { "exceptions" "a sequence of " { $link fp-exception } " symbols" } }
+{ $values { "exceptions" { $sequence fp-exception } } }
{ $description "Replaces the set of floating-point exception flags with the set specified in " { $snippet "exceptions" } "." }
{ $notes "On Intel platforms, the legacy x87 floating-point unit does not support setting exception flags, so this word only clears the x87 exception flags. However, the SSE unit's flags are set as expected." } ;
{ $description "Clears all of the floating-point exception flags." } ;
HELP: collect-fp-exceptions
-{ $values { "quot" quotation } { "exceptions" "a sequence of " { $link fp-exception } " symbols" } }
+{ $values { "quot" quotation } { "exceptions" { $sequence fp-exception } } }
{ $description "Clears the floating-point exception flags and then calls " { $snippet "quot" } ", returning the set of floating-point exceptions raised during its execution and placing them on the datastack on " { $snippet "quot" } "'s completion." } ;
{ fp-exception-flags set-fp-exception-flags clear-fp-exception-flags collect-fp-exceptions } related-words
{ rounding-mode with-rounding-mode } related-words
HELP: fp-traps
-{ $values { "exceptions" "a sequence of " { $link fp-exception } " symbols" } }
+{ $values { "exceptions" { $sequence fp-exception } } }
{ $description "Returns the set of floating point exceptions with processor traps currently set." } ;
HELP: with-fp-traps
-{ $values { "exceptions" "a sequence of " { $link fp-exception } " symbols" } { "quot" quotation } }
-{ $description "Replaces the floating-point exception mask to enable processor traps to be raised for the set of exception conditions specified in " { $snippet "exceptions" } " for the dynamic extent of " { $snippet "quot" } ", restoring the original exception mask on " { $snippet "quot" } "'s completion." } ;
+{ $values { "exceptions" { $sequence fp-exception } } { "quot" quotation } }
+{ $description "Clears the floating-point exception flags and replaces the exception mask, enabling processor traps for the set of exception conditions specified in " { $snippet "exceptions" } " for the dynamic extent of " { $snippet "quot" } ". The original exception mask is restored on " { $snippet "quot" } "'s completion." } ;
HELP: without-fp-traps
{ $values { "quot" quotation } }
{ $description "Disables all floating-pointer processor traps for the dynamic extent of " { $snippet "quot" } ", restoring the original exception mask on " { $snippet "quot" } "'s completion." } ;
-{ fp-traps with-fp-traps without-fp-traps } related-words
+{ fp-traps with-fp-traps without-fp-traps vm-error>exception-flags vm-error-exception-flag? } related-words
+
+HELP: vm-error>exception-flags
+{ $values { "error" "a floating-point error object from the Factor VM" } { "exceptions" { $sequence fp-exception } } }
+{ $description "When a floating-point trap is raised, the Factor VM reports the trap by throwing a Factor exception containing the exception flags at the time the trap was raised. This word extracts the exception flag information from " { $snippet "error" } " and converts it into a sequence of " { $link fp-exception } "s." } ;
+
+HELP: vm-error-exception-flag?
+{ $values { "error" "a floating-point error object from the Factor VM" } { "flag" fp-exception } { "?" boolean } }
+{ $description "When a floating-point trap is raised, the Factor VM reports the trap by throwing a Factor exception containing the exception flags at the time the trap was raised. This word returns a boolean indicating whether the exception " { $snippet "flag" } " was raised at the time " { $snippet "error" } " was thrown." } ;
ARTICLE: "math.floats.env" "Controlling the floating-point environment"
"The " { $vocab-link "math.floats.env" } " vocabulary contains words for querying and controlling the floating-point environment."
$nl
"Querying and setting exception flags:"
-{ $subsection fp-exception-flags }
-{ $subsection set-fp-exception-flags }
-{ $subsection clear-fp-exception-flags }
-{ $subsection collect-fp-exceptions }
+{ $subsections
+ fp-exception-flags
+ set-fp-exception-flags
+ clear-fp-exception-flags
+ collect-fp-exceptions
+}
"Querying and controlling processor traps for floating-point exceptions:"
-{ $subsection fp-traps }
-{ $subsection with-fp-traps }
-{ $subsection without-fp-traps }
+{ $subsections
+ fp-traps
+ with-fp-traps
+ without-fp-traps
+}
+"Getting the floating-point exception state from errors raised by enabled traps:"
+{ $subsections
+ vm-error>exception-flags
+ vm-error-exception-flag?
+}
"Querying and controlling the rounding mode and treatment of denormals:"
-{ $subsection rounding-mode }
-{ $subsection with-rounding-mode }
-{ $subsection denormal-mode }
-{ $subsection with-denormal-mode }
-{ $notes "On PowerPC, the above words only modify the scalar FPU's state (in FPSCR); the AltiVec unit is currently unaffected." } ;
+{ $subsections
+ rounding-mode
+ with-rounding-mode
+ denormal-mode
+ with-denormal-mode
+} ;
ABOUT: "math.floats.env"
projects / factor.git / blobdiff