├── .gitattributes ├── .github ├── dependabot.yml └── workflows │ └── main.yml ├── .gitignore ├── CHANGELOG.md ├── CONTRIBUTING.md ├── Cargo.toml ├── LICENSE-APACHE ├── LICENSE-MIT ├── README.md ├── README.tpl ├── js └── hooks.js ├── live-allocations-dump.png ├── package.json ├── src ├── hooks.rs └── lib.rs └── tests └── readme_up_to_date.rs /.gitattributes: -------------------------------------------------------------------------------- 1 | README.md -diff -merge 2 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: cargo 4 | directory: "/" 5 | schedule: 6 | interval: daily 7 | time: "08:00" 8 | open-pull-requests-limit: 10 9 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | on: [push, pull_request] 3 | 4 | jobs: 5 | test: 6 | name: Test 7 | runs-on: ubuntu-latest 8 | steps: 9 | - uses: actions/checkout@master 10 | - name: Install Rust 11 | run: rustup update stable && rustup default stable 12 | - run: cargo install cargo-readme --vers "^3" 13 | - run: cargo test 14 | 15 | rustfmt: 16 | name: Rustfmt 17 | runs-on: ubuntu-latest 18 | steps: 19 | - uses: actions/checkout@master 20 | - name: Install Rust 21 | run: rustup update stable && rustup default stable && rustup component add rustfmt 22 | - run: cargo fmt -- --check 23 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /target 2 | **/*.rs.bk 3 | Cargo.lock 4 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Unreleased 2 | 3 | Released YYYY-MM-DD. 4 | 5 | * TODO 6 | 7 | -------------------------------------------------------------------------------- 8 | 9 | # 0.1.1 10 | 11 | Released 2019-05-10. 12 | 13 | * Fixed a bug with the way that `realloc`s were traced. 14 | 15 | -------------------------------------------------------------------------------- 16 | 17 | # 0.1.0 18 | 19 | Released 2019-05-10. 20 | 21 | Initial release! 22 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to `wasm-tracing-allocator` 2 | 3 | Hi! We'd love to have your contributions! If you want help or mentorship, reach 4 | out to us in a GitHub issue, or ping `fitzgen` in [`#wg-wasm` on the Rust 5 | Programming Language Discord server](https://discordapp.com/invite/rust-lang) 6 | and introduce yourself. 7 | 8 | 9 | 10 | 11 | 12 | - [Code of Conduct](#code-of-conduct) 13 | - [Building and Testing](#building-and-testing) 14 | - [Prerequisites](#prerequisites) 15 | - [Building](#building) 16 | - [Updating the `README.md`](#updating-the-readmemd) 17 | - [Testing](#testing) 18 | - [Automatic Code Formatting](#automatic-code-formatting) 19 | - [Contributions We Want](#contributions-we-want) 20 | 21 | 22 | 23 | ## Code of Conduct 24 | 25 | We abide by the [Rust Code of Conduct][coc] and ask that you do as well. 26 | 27 | [coc]: https://www.rust-lang.org/en-US/conduct.html 28 | 29 | ## Building and Testing 30 | 31 | ### Prerequisites 32 | 33 | Ensure that you have `cargo-readme` installed: 34 | 35 | ``` 36 | $ cargo install cargo-readme 37 | ``` 38 | 39 | ### Building 40 | 41 | ``` 42 | cargo build 43 | ``` 44 | 45 | ### Updating the `README.md` 46 | 47 | ``` 48 | cargo readme > README.md 49 | ``` 50 | 51 | ### Testing 52 | 53 | ``` 54 | cargo test 55 | ``` 56 | 57 | ## Automatic Code Formatting 58 | 59 | We use [`rustfmt`](https://github.com/rust-lang-nursery/rustfmt) to enforce a 60 | consistent code style across the whole code base. 61 | 62 | You can install the latest version of `rustfmt` with this command: 63 | 64 | ``` 65 | rustup component add rustfmt 66 | ``` 67 | 68 | Once that is taken care of, you can (re)format all code by running this command 69 | from the root of the repository: 70 | 71 | ``` 72 | cargo fmt --all 73 | ``` 74 | 75 | ## Contributions We Want 76 | 77 | * **Bug fixes!** Include a regression test if possible. 78 | 79 | * **New analyses of allocations and deallocations!** File an issue before hand 80 | outlining the new analysis so we can all get on the same page and make sure it 81 | is the most awesome version of the analysis it can be. 82 | 83 | * **Performance improvements!** The tracing has a lot of overhead, and if there 84 | are relatively easy ways to reduce that overhead, we'd like to do that. 85 | -------------------------------------------------------------------------------- /Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | authors = ["Nick Fitzgerald ", "The Rust and WebAssembly Working Group"] 3 | categories = ["memory-management", "wasm", "development-tools::debugging", "development-tools::profiling"] 4 | description = "A global allocator for Wasm that traces allocations and deallocations for debugging purposes." 5 | edition = "2018" 6 | license = "MIT/Apache-2.0" 7 | name = "wasm-tracing-allocator" 8 | readme = "./README.md" 9 | repository = "https://github.com/rustwasm/wasm-tracing-allocator" 10 | version = "0.1.1" 11 | 12 | [dependencies] 13 | wasm-bindgen = "0.2.43" 14 | -------------------------------------------------------------------------------- /LICENSE-APACHE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /LICENSE-MIT: -------------------------------------------------------------------------------- 1 | Copyright (c) 2014 Alex Crichton 2 | 3 | Permission is hereby granted, free of charge, to any 4 | person obtaining a copy of this software and associated 5 | documentation files (the "Software"), to deal in the 6 | Software without restriction, including without 7 | limitation the rights to use, copy, modify, merge, 8 | publish, distribute, sublicense, and/or sell copies of 9 | the Software, and to permit persons to whom the Software 10 | is furnished to do so, subject to the following 11 | conditions: 12 | 13 | The above copyright notice and this permission notice 14 | shall be included in all copies or substantial portions 15 | of the Software. 16 | 17 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF 18 | ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 19 | TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 20 | PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 21 | SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 22 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 23 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR 24 | IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 25 | DEALINGS IN THE SOFTWARE. 26 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |
2 | 3 |

wasm-tracing-allocator

4 | 5 | A global allocator for Wasm that traces allocations and deallocations for debugging purposes. 6 | 7 |

8 | Crates.io version 9 | Download 10 | docs.rs docs 11 |

12 | 13 |

14 | API Docs 15 | | 16 | Contributing 17 | | 18 | Chat 19 |

20 | 21 | Built with 🦀🕸 by The Rust and WebAssembly Working Group 22 |
23 | 24 | 25 | ### About 26 | 27 | `wasm-tracing-allocator` enables you to better debug and analyze memory leaks 28 | and invalid frees in an environment where we don't have access to the 29 | conventional tools like Valgrind. The tracing hooks are safely implemented in 30 | JS, outside the Wasm module and its linear memory, to ensure that the tracing 31 | code doesn't perturb results. 32 | 33 | ### Table of Contents 34 | 35 | * [Enabling the Tracing Allocator](#enabling-the-tracing-allocator) 36 | * [Analyzing and Debugging](#analyzing-and-debugging) 37 | 38 | ### Enabling the Tracing Allocator 39 | 40 | First, add `wasm-tracing-allocator` to your `Cargo.toml`'s dependency list: 41 | 42 | ```toml 43 | [dependencies] 44 | wasm-tracing-allocator = "0.1.0" 45 | ``` 46 | 47 | Next, configure `wasm_tracing_allocator::WasmTracingAllocator` as the global 48 | allocator: 49 | 50 | ```rust 51 | // src/lib.rs 52 | 53 | use std::alloc::System; 54 | use wasm_tracing_allocator::WasmTracingAllocator; 55 | 56 | #[global_allocator] 57 | static GLOBAL_ALLOCATOR: WasmTracingAllocator = WasmTracingAllocator(System); 58 | ``` 59 | 60 | Finally, make the JS implementations of the tracing hooks are available for your 61 | Wasm module to import: 62 | 63 | * On the Web, add this script *before* your Wasm module is instantiated: 64 | 65 | ```html 66 | 67 | ``` 68 | 69 | * On Node.js, require the hooks *before* your Wasm module is instantiated: 70 | 71 | ```js 72 | require("wasm-tracing-allocator"); 73 | ``` 74 | 75 | ### Analyzing and Debugging 76 | 77 | Use your developer tools console to invoke methods of the global 78 | `WasmTracingAllocator` object to get analyses about allocations and 79 | deallocations. 80 | 81 | The output is typically rendered with `console.table`: 82 | 83 | [![Example output](https://raw.githubusercontent.com/rustwasm/wasm-tracing-allocator/master/live-allocations-dump.png)](https://raw.githubusercontent.com/rustwasm/wasm-tracing-allocator/master/live-allocations-dump.png) 84 | 85 | #### `WasmTracingAllocator.dumpLiveAllocations` 86 | 87 | Dump a table of live allocations to the console. 88 | 89 | ```js 90 | WasmTracingAllocator.dumpLiveAllocations({ 91 | keyLabel: String, 92 | valueLabel: String, 93 | getKey: Object => any, 94 | getValue: Object => Number, 95 | }); 96 | ``` 97 | 98 | * `keyLabel`: Optional. The string label used to describe the keys column in the 99 | table. 100 | 101 | * `valueLabel`: Optional. The string label used to describe the values column in 102 | the table. 103 | 104 | * `getKey`: Optional. Function from an allocation entry object to anything. The 105 | table will group and aggregate entries by their keys. Defaults to the stack at 106 | the time of the allocation. 107 | 108 | * `getValue`: Optional. Function from an allocation entry object to a 109 | number. The values for all entries with the same key are summed. Defaults to 110 | the byte size of each allocation; a potential alternative would be to ignore 111 | the argument and return `1` to count the number of allocations instead. 112 | 113 | #### `WasmTracingAllocator.dumpInvalidFrees` 114 | 115 | Dump a table of invalid frees (double frees, frees of things that were never 116 | allocated, etc...) to the console. 117 | 118 | ```js 119 | WasmTracingAllocator.dumpInvalidFrees({ 120 | keyLabel: String, 121 | valueLabel: String, 122 | getKey: Object => any, 123 | getValue: Object => Number, 124 | }); 125 | ``` 126 | 127 | * `keyLabel`: Optional. The string label used to describe the keys column in the 128 | table. 129 | 130 | * `valueLabel`: Optional. The string label used to describe the values column in 131 | the table. 132 | 133 | * `getKey`: Optional. Function from an invalid free entry object to anything. The 134 | table will group and aggregate entries by their keys. Defaults to the stack at 135 | the time of the deallocation. 136 | 137 | * `getValue`: Optional. Function from an invalid free entry object to a 138 | number. The values for all entries with the same key are summed. Defaults to 139 | counting the number of invalid frees. 140 | 141 | -------------------------------------------------------------------------------- /README.tpl: -------------------------------------------------------------------------------- 1 |
2 | 3 |

wasm-tracing-allocator

4 | 5 | A global allocator for Wasm that traces allocations and deallocations for debugging purposes. 6 | 7 |

8 | Crates.io version 9 | Download 10 | docs.rs docs 11 |

12 | 13 |

14 | API Docs 15 | | 16 | Contributing 17 | | 18 | Chat 19 |

20 | 21 | Built with 🦀🕸 by The Rust and WebAssembly Working Group 22 |
23 | 24 | {{readme}} 25 | -------------------------------------------------------------------------------- /js/hooks.js: -------------------------------------------------------------------------------- 1 | (function () { 2 | class Allocation { 3 | constructor(size, align, pointer) { 4 | this.size = size; 5 | this.align = align; 6 | this.pointer = pointer; 7 | this.stack = getStack(); 8 | } 9 | } 10 | 11 | class InvalidFree { 12 | constructor(size, align, pointer) { 13 | this.size = size; 14 | this.align = align; 15 | this.pointer = pointer; 16 | this.stack = getStack(); 17 | } 18 | } 19 | 20 | const liveAllocs = new Map(); 21 | const invalidFrees = []; 22 | 23 | function getStack() { 24 | return Error() 25 | .stack 26 | .split("\n") 27 | .filter(frame => frame.match(/hooks\.js/) === null) 28 | .join("\n"); 29 | } 30 | 31 | function onAlloc(size, align, pointer) { 32 | liveAllocs.set(pointer, new Allocation(size, align, pointer)); 33 | } 34 | 35 | function onDealloc(size, align, pointer) { 36 | const wasLive = liveAllocs.delete(pointer); 37 | if (!wasLive) { 38 | invalidFrees.push(new InvalidFree(size, align, pointer)); 39 | } 40 | } 41 | 42 | function onAllocZeroed(size, align, pointer) { 43 | onAlloc(size, align, pointer); 44 | } 45 | 46 | function onRealloc( 47 | oldPointer, 48 | newPointer, 49 | oldSize, 50 | newSize, 51 | align, 52 | ) { 53 | onDealloc(oldSize, align, oldPointer); 54 | onAlloc(newSize, align, newPointer); 55 | } 56 | 57 | function dumpTable(entries, { keyLabel, valueLabel, getKey, getValue }) { 58 | const byKey = new Map; 59 | let total = 0; 60 | 61 | for (const entry of entries) { 62 | const key = getKey(entry); 63 | const keyValue = byKey.get(key) || 0; 64 | const entryValue = getValue(entry); 65 | total += entryValue; 66 | byKey.set(key, keyValue + entryValue); 67 | } 68 | 69 | const table = [...byKey] 70 | .sort((a, b) => b[1] - a[1]) 71 | .map(a => ({ [keyLabel]: a[0], [valueLabel]: a[1] })); 72 | 73 | table.unshift({ [keyLabel]: "", [valueLabel]: total }); 74 | 75 | console.table(table, [keyLabel, valueLabel]); 76 | } 77 | 78 | function getGlobal() { 79 | if (typeof self !== 'undefined') { return self; } 80 | if (typeof window !== 'undefined') { return window; } 81 | if (typeof global !== 'undefined') { return global; } 82 | throw new Error('unable to locate global object'); 83 | } 84 | 85 | getGlobal().WasmTracingAllocator = { 86 | on_alloc: onAlloc, 87 | on_dealloc: onDealloc, 88 | on_alloc_zeroed: onAllocZeroed, 89 | on_realloc: onRealloc, 90 | 91 | dumpLiveAllocations(opts) { 92 | dumpTable(liveAllocs.values(), Object.assign({ 93 | keyLabel: "Live Allocations", 94 | valueLabel: "Size (Bytes)", 95 | getKey: entry => entry.stack, 96 | getValue: _entry => 1, 97 | }, opts)); 98 | }, 99 | 100 | dumpInvalidFrees(opts) { 101 | dumpTable(invalidFrees, Object.assign({ 102 | keyLabel: "Invalid Free", 103 | valueLabel: "Count", 104 | getKey: entry => entry.stack, 105 | getValue: _entry => 1, 106 | }, opts)); 107 | }, 108 | }; 109 | }()); 110 | -------------------------------------------------------------------------------- /live-allocations-dump.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rustwasm/wasm-tracing-allocator/216623e135eae91ac98be4d6e7e29f276a0f2701/live-allocations-dump.png -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "wasm-tracing-allocator", 3 | "version": "0.1.1", 4 | "description": "", 5 | "main": "js/hooks.js", 6 | "directories": { 7 | "test": "tests" 8 | }, 9 | "files": ["js/*.js"], 10 | "scripts": { 11 | "test": "echo \"Error: no test specified\" && exit 1" 12 | }, 13 | "repository": { 14 | "type": "git", 15 | "url": "git+https://github.com/rustwasm/wasm-tracing-allocator.git" 16 | }, 17 | "keywords": [ 18 | "wasm", 19 | "rust", 20 | "webassembly", 21 | "allocator", 22 | "memory-leak", 23 | "use-after-free" 24 | ], 25 | "author": "Nick Fitzgerald", 26 | "license": "MIT OR Apache-2.0", 27 | "bugs": { 28 | "url": "https://github.com/rustwasm/wasm-tracing-allocator/issues" 29 | }, 30 | "homepage": "https://github.com/rustwasm/wasm-tracing-allocator#readme" 31 | } 32 | -------------------------------------------------------------------------------- /src/hooks.rs: -------------------------------------------------------------------------------- 1 | use wasm_bindgen::prelude::*; 2 | 3 | #[wasm_bindgen] 4 | extern "C" { 5 | /// Invoked after each `GlobalAlloc::alloc`. 6 | #[wasm_bindgen(js_namespace = WasmTracingAllocator)] 7 | pub fn on_alloc(size: usize, align: usize, pointer: *mut u8); 8 | 9 | /// Invoked after each `GlobalAlloc::dealloc`. 10 | #[wasm_bindgen(js_namespace = WasmTracingAllocator)] 11 | pub fn on_dealloc(size: usize, align: usize, pointer: *mut u8); 12 | 13 | /// Invoked after each `GlobalAlloc::alloc_zeroed`. 14 | #[wasm_bindgen(js_namespace = WasmTracingAllocator)] 15 | pub fn on_alloc_zeroed(size: usize, align: usize, pointer: *mut u8); 16 | 17 | /// Invoked after each `GlobalAlloc::realloc`. 18 | #[wasm_bindgen(js_namespace = WasmTracingAllocator)] 19 | pub fn on_realloc( 20 | old_pointer: *mut u8, 21 | new_pointer: *mut u8, 22 | old_size: usize, 23 | new_size: usize, 24 | align: usize, 25 | ); 26 | } 27 | -------------------------------------------------------------------------------- /src/lib.rs: -------------------------------------------------------------------------------- 1 | /*! 2 | 3 | ## About 4 | 5 | `wasm-tracing-allocator` enables you to better debug and analyze memory leaks 6 | and invalid frees in an environment where we don't have access to the 7 | conventional tools like Valgrind. The tracing hooks are safely implemented in 8 | JS, outside the Wasm module and its linear memory, to ensure that the tracing 9 | code doesn't perturb results. 10 | 11 | ## Table of Contents 12 | 13 | * [Enabling the Tracing Allocator](#enabling-the-tracing-allocator) 14 | * [Analyzing and Debugging](#analyzing-and-debugging) 15 | 16 | ## Enabling the Tracing Allocator 17 | 18 | First, add `wasm-tracing-allocator` to your `Cargo.toml`'s dependency list: 19 | 20 | ```toml 21 | [dependencies] 22 | wasm-tracing-allocator = "0.1.0" 23 | ``` 24 | 25 | Next, configure `wasm_tracing_allocator::WasmTracingAllocator` as the global 26 | allocator: 27 | 28 | ```no_run 29 | // src/lib.rs 30 | # fn main() {} 31 | 32 | use std::alloc::System; 33 | use wasm_tracing_allocator::WasmTracingAllocator; 34 | 35 | #[global_allocator] 36 | static GLOBAL_ALLOCATOR: WasmTracingAllocator = WasmTracingAllocator(System); 37 | ``` 38 | 39 | Finally, make the JS implementations of the tracing hooks are available for your 40 | Wasm module to import: 41 | 42 | * On the Web, add this script *before* your Wasm module is instantiated: 43 | 44 | ```html 45 | 46 | ``` 47 | 48 | * On Node.js, require the hooks *before* your Wasm module is instantiated: 49 | 50 | ```js 51 | require("wasm-tracing-allocator"); 52 | ``` 53 | 54 | ## Analyzing and Debugging 55 | 56 | Use your developer tools console to invoke methods of the global 57 | `WasmTracingAllocator` object to get analyses about allocations and 58 | deallocations. 59 | 60 | The output is typically rendered with `console.table`: 61 | 62 | [![Example output](https://raw.githubusercontent.com/rustwasm/wasm-tracing-allocator/master/live-allocations-dump.png)](https://raw.githubusercontent.com/rustwasm/wasm-tracing-allocator/master/live-allocations-dump.png) 63 | 64 | ### `WasmTracingAllocator.dumpLiveAllocations` 65 | 66 | Dump a table of live allocations to the console. 67 | 68 | ```js 69 | WasmTracingAllocator.dumpLiveAllocations({ 70 | keyLabel: String, 71 | valueLabel: String, 72 | getKey: Object => any, 73 | getValue: Object => Number, 74 | }); 75 | ``` 76 | 77 | * `keyLabel`: Optional. The string label used to describe the keys column in the 78 | table. 79 | 80 | * `valueLabel`: Optional. The string label used to describe the values column in 81 | the table. 82 | 83 | * `getKey`: Optional. Function from an allocation entry object to anything. The 84 | table will group and aggregate entries by their keys. Defaults to the stack at 85 | the time of the allocation. 86 | 87 | * `getValue`: Optional. Function from an allocation entry object to a 88 | number. The values for all entries with the same key are summed. Defaults to 89 | the byte size of each allocation; a potential alternative would be to ignore 90 | the argument and return `1` to count the number of allocations instead. 91 | 92 | ### `WasmTracingAllocator.dumpInvalidFrees` 93 | 94 | Dump a table of invalid frees (double frees, frees of things that were never 95 | allocated, etc...) to the console. 96 | 97 | ```js 98 | WasmTracingAllocator.dumpInvalidFrees({ 99 | keyLabel: String, 100 | valueLabel: String, 101 | getKey: Object => any, 102 | getValue: Object => Number, 103 | }); 104 | ``` 105 | 106 | * `keyLabel`: Optional. The string label used to describe the keys column in the 107 | table. 108 | 109 | * `valueLabel`: Optional. The string label used to describe the values column in 110 | the table. 111 | 112 | * `getKey`: Optional. Function from an invalid free entry object to anything. The 113 | table will group and aggregate entries by their keys. Defaults to the stack at 114 | the time of the deallocation. 115 | 116 | * `getValue`: Optional. Function from an invalid free entry object to a 117 | number. The values for all entries with the same key are summed. Defaults to 118 | counting the number of invalid frees. 119 | 120 | */ 121 | 122 | #![deny(missing_docs, missing_debug_implementations)] 123 | 124 | use std::alloc::{GlobalAlloc, Layout}; 125 | 126 | #[doc(hidden)] 127 | pub mod hooks; 128 | 129 | /// A global allocator that traces the Wasm module's allocations and 130 | /// deallocations. 131 | /// 132 | /// It wraps some global allocator `A` that actually implements the allocation 133 | /// and deallocation, and inserts its tracing after each invocation. 134 | /// 135 | /// ## Example 136 | /// 137 | /// Just give it the global allocator `A` to wrap, and add the 138 | /// `#[global_allocator]` attribute. The module level documentation has an 139 | /// example of wrapping the default system allocator. Here is an example of 140 | /// wrapping [`wee_alloc`](https://github.com/rustwasm/wee_alloc): 141 | /// 142 | /// ```ignore 143 | /// // src/lib.rs 144 | /// # fn main() {} 145 | /// 146 | /// use wasm_tracing_allocator::WasmTracingAllocator; 147 | /// use wee_alloc::WeeAlloc; 148 | /// 149 | /// #[global_allocator] 150 | /// static GLOBAL_ALLOCATOR: WasmTracingAllocator = 151 | /// WasmTracingAllocator(WeeAlloc::INIT); 152 | /// ``` 153 | #[derive(Debug)] 154 | pub struct WasmTracingAllocator(pub A) 155 | where 156 | A: GlobalAlloc; 157 | 158 | unsafe impl GlobalAlloc for WasmTracingAllocator 159 | where 160 | A: GlobalAlloc, 161 | { 162 | unsafe fn alloc(&self, layout: Layout) -> *mut u8 { 163 | let size = layout.size(); 164 | let align = layout.align(); 165 | let pointer = self.0.alloc(layout); 166 | hooks::on_alloc(size, align, pointer); 167 | pointer 168 | } 169 | 170 | unsafe fn dealloc(&self, pointer: *mut u8, layout: Layout) { 171 | let size = layout.size(); 172 | let align = layout.align(); 173 | self.0.dealloc(pointer, layout); 174 | hooks::on_dealloc(size, align, pointer); 175 | } 176 | 177 | unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8 { 178 | let size = layout.size(); 179 | let align = layout.align(); 180 | let pointer = self.0.alloc_zeroed(layout); 181 | hooks::on_alloc_zeroed(size, align, pointer); 182 | pointer 183 | } 184 | 185 | unsafe fn realloc(&self, old_pointer: *mut u8, layout: Layout, new_size: usize) -> *mut u8 { 186 | let old_size = layout.size(); 187 | let align = layout.align(); 188 | let new_pointer = self.0.realloc(old_pointer, layout, new_size); 189 | hooks::on_realloc(old_pointer, new_pointer, old_size, new_size, align); 190 | new_pointer 191 | } 192 | } 193 | -------------------------------------------------------------------------------- /tests/readme_up_to_date.rs: -------------------------------------------------------------------------------- 1 | use std::fs; 2 | use std::process::Command; 3 | 4 | #[test] 5 | fn cargo_readme_up_to_date() { 6 | println!("Checking that `cargo readme > README.md` is up to date..."); 7 | 8 | let expected = Command::new("cargo") 9 | .arg("readme") 10 | .current_dir(env!("CARGO_MANIFEST_DIR")) 11 | .output() 12 | .expect("should run `cargo readme` OK") 13 | .stdout; 14 | let expected = String::from_utf8_lossy(&expected); 15 | 16 | let actual = fs::read_to_string(concat!(env!("CARGO_MANIFEST_DIR"), "/README.md")) 17 | .expect("should read README.md OK"); 18 | 19 | if actual != expected { 20 | panic!("Run `cargo readme > README.md` to update README.md"); 21 | } 22 | } 23 | --------------------------------------------------------------------------------