# hs.crash

Various features/facilities for developers who are working on Hammerspoon itself, or writing extensions for it. It is extremely unlikely that you should need any part of this extension, in a normal user configuration.

---

## API Overview
**Functions** - _API calls offered directly by the extension_
 * [attemptMemoryRelease](#attemptmemoryrelease)
 * [crash](#crash)
 * [crashKV](#crashkv)
 * [crashLog](#crashlog)
 * [dumpCLIBS](#dumpclibs)
 * [residentSize](#residentsize)
 * [throwObjCException](#throwobjcexception)

---

## API Documentation

#### Functions

### [attemptMemoryRelease](#attemptmemoryrelease)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.crash.attemptMemoryRelease()`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Attempts to reduce RAM usage of Hammerspoon                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | <ul><li>This function will print some memory usage numbers (in bytes) to the Hammerspoon Console before and after forcing Lua's garbage collector</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [extensions/crash/crash.lua line 40](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/crash/crash.lua#L40) |

---

### [crash](#crash)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.crash.crash()`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Causes Hammerspoon to immediately crash                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | <ul><li>This is for testing purposes only, you are extremely unlikely to need this in normal Hammerspoon usage</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [extensions/crash/libcrash.m line 12](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/crash/libcrash.m#L12) |

---

### [crashKV](#crashkv)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.crash.crashKV(key, value)`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Sets a key/value pair in any Sentry crash dump generated by this Hammerspoon session                                                                     |
| **Parameters**                              | <ul><li>key - A string containing the key name of the pair</li><li>value - A string containing the value of the pair</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | None |
| **Examples**                                | None |
| **Source**                                  | [extensions/crash/libcrash.m line 72](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/crash/libcrash.m#L72) |

---

### [crashLog](#crashlog)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.crash.crashLog(logMessage)`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Leaves a breadcrumb log message in any Sentry crash dump generated by this Hammerspoon session                                                                     |
| **Parameters**                              | <ul><li>logMessage - A string containing a message to log</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | <ul><li>This is probably only useful to extension developers. If you are trying to track down a confusing crash, and you have access to the Sentry project for Hammerspoon (or access to someone who has access!), this can be a useful way to leave breadcrumbs from Lua in the crash dump</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [extensions/crash/libcrash.m line 53](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/crash/libcrash.m#L53) |

---

### [dumpCLIBS](#dumpclibs)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.crash.dumpCLIBS() -> table`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Dumps the contents of Lua's CLIBS registry                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>A table containing all the paths of C libraries that have been loaded into the Lua runtime</li></ul>          |
| **Notes**                                   | <ul><li>This is probably only useful to extension developers as a useful way of ensuring that you are loading C libraries from the places you expect.</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [extensions/crash/crash.lua line 7](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/crash/crash.lua#L7) |

---

### [residentSize](#residentsize)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.crash.residentSize() -> integer or nil`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Gets the resident size of the Hammerspoon process                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>An integer containing the amount of RAM in use by Hammerspoon (in bytes), or nil if an error occurred</li></ul>          |
| **Notes**                                   | None |
| **Examples**                                | None |
| **Source**                                  | [extensions/crash/libcrash.m line 107](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/crash/libcrash.m#L107) |

---

### [throwObjCException](#throwobjcexception)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.crash.throwObjCException(name, message)`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Causes Hammerspoon to generate an Objective C exception                                                                     |
| **Parameters**                              | <ul><li>name - A string containing the name of the exception</li><li>message - A human readable string explaining the exception</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | <ul><li>Outside of a context of a Lua pcall() (or a C lua_pcall()), this will cause Hammerspoon to exit. We follow the safe behaviour of terminating the app on any unhandled Objective C exception.</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [extensions/crash/libcrash.m line 31](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/crash/libcrash.m#L31) |

---

---

<script src="https://giscus.app/client.js"
        data-repo="CommandPost/CommandPost"
        data-repo-id="MDEwOlJlcG9zaXRvcnk3NDY0NTk2NQ=="
        data-category="Website Discussion"
        data-category-id="DIC_kwDOBHMBzc4CXFFA"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="dark"
        data-lang="en"
        crossorigin="anonymous"
        async>
</script>
