• Top
  • Documentation
  • Books
  • Boolean-reasoning
  • Projects
  • Debugging
  • Std
  • Proof-automation
  • Macro-libraries
  • ACL2
    • Theories
    • Rule-classes
    • Proof-builder
    • Recursion-and-induction
    • Hons-and-memoization
    • Events
    • Parallelism
    • History
    • Programming
      • Defun
      • Declare
      • System-utilities
      • Stobj
        • Defstobj
        • Defabsstobj
        • Stobj-table
        • Preservation-thms
        • Nested-stobjs
        • Defrstobj
        • With-global-stobj
        • User-stobjs-modified-warnings
        • Stobj-example-1
        • Defrstobj
        • Stobj-example-3
        • Stobj-example-1-proofs
        • With-local-stobj
        • Stobj-example-1-defuns
        • Declare-stobjs
        • Trans-eval-and-stobjs
        • With-local-state
        • Stobj-example-2
        • Stobj-example-1-implementation
        • Add-global-stobj
        • Swap-stobjs
        • Resize-list
        • Nth-aliases-table
        • Def-stobj-frame
        • Trans-eval-and-locally-bound-stobjs
        • Std/stobjs
        • Count-keys
        • Update-nth-array
        • Remove-global-stobj
      • State
      • Mutual-recursion
      • Memoize
      • Mbe
      • Io
      • Defpkg
      • Apply$
      • Loop$
      • Programming-with-state
      • Arrays
      • Characters
      • Time$
      • Defmacro
      • Loop$-primer
      • Fast-alists
      • Defconst
      • Evaluation
      • Guard
      • Equality-variants
      • Compilation
      • Hons
      • ACL2-built-ins
      • Developers-guide
      • System-attachments
      • Advanced-features
      • Set-check-invariant-risk
      • Numbers
      • Efficiency
      • Irrelevant-formals
      • Introduction-to-programming-in-ACL2-for-those-who-know-lisp
      • Redefining-programs
      • Lists
      • Invariant-risk
      • Errors
      • Defabbrev
      • Conses
      • Alists
      • Set-register-invariant-risk
      • Strings
      • Program-wrapper
      • Get-internal-time
      • Basics
      • Packages
      • Oracle-eval
      • Defmacro-untouchable
      • <<
      • Primitive
      • Revert-world
      • Unmemoize
      • Set-duplicate-keys-action
      • Symbols
      • Def-list-constructor
      • Easy-simplify-term
      • Defiteration
      • Fake-oracle-eval
      • Defopen
      • Sleep
    • Operational-semantics
    • Real
    • Start-here
    • Debugging
    • Miscellaneous
    • Output-controls
    • Macros
    • Interfacing-tools
  • Interfacing-tools
  • Hardware-verification
  • Software-verification
  • Math
  • Testing-utilities

• Events
• Stobj

Add-global-stobj

Add a global stobj with a given name

See stobj for background on stobjs, and see defstobj and defabsstobj for further background.

We start with the General Form and an Example Form, which are followed by discussions of global stobjs and the effect of this utility.

General Form:
(add-global-stobj x state)

where x evaluates to the name of a stobj that does not already have a global value, either because it was introduced by defstobj or defabsstobj with keyword value :non-executable t or because remove-global-stobj was previously applied to that name.

Example Form:
(add-global-stobj 'st state) ; st non-global from defstobj or defabsstobj

By default, defstobj and defabsstobj create a “live”, mutable object for the given name that can be referenced at the top level, which we call a “global” stobj. This is illustrated by the following log.

ACL2 !>(defstobj st fld)

Summary
Form:  ( DEFSTOBJ ST ...)
Rules: NIL
Time:  0.02 seconds (prove: 0.00, print: 0.00, other: 0.02)
 ST
ACL2 !>st ; global stobj for the name, ST
<st>
ACL2 !>(fld st)
NIL
ACL2 !>(update-fld 3 st)
<st>
ACL2 !>(fld st)
3
ACL2 !>

However, the following log shows that we can introduce a stobj without creating a global stobj, by using the keyword value :non-executable t.

ACL2 !>(defstobj st2 fld2 :non-executable t)

Summary
Form:  ( DEFSTOBJ ST2 ...)
Rules: NIL
Time:  0.02 seconds (prove: 0.00, print: 0.00, other: 0.02)
 ST2
ACL2 !>(fld2 st2)


ACL2 Error [Evaluation] in TOP-LEVEL:  Unbound var ST2.  Note that
ST2 is a non-executable stobj.

ACL2 !>

The function add-global-stobj creates a global stobj for a given stobj name when one does not already exist. Let's continue the log started immediately above.

ACL2 !>(add-global-stobj 'st2 state)
 ST2
ACL2 !>(fld2 st2)
NIL
ACL2 !>(update-fld2 3 st2)
<st2>
ACL2 !>(fld2 st2)
3
ACL2 !>

The function remove-global-stobj removes the indicated global stobj. We continue the log above.

ACL2 !>(remove-global-stobj 'st2 state)
 ST2
ACL2 !>(fld2 st2)


ACL2 Error [Evaluation] in TOP-LEVEL:  Unbound var ST2.  Note that
ST2 is a non-executable stobj.

ACL2 !>

If we remove a global stobj, as shown just above, and then add the corresponding global stobj, we get a fresh copy of that stobj; all previous updates are discarded.

ACL2 !>(add-global-stobj 'st2 state)
 ST2
ACL2 !>(fld2 st2)
NIL
ACL2 !>