|
1 |
| -# gm_asyncio |
| 1 | +# gm_asyncio [![Build][1]][2] |
2 | 2 | Make your Garry's Mod I/O asynchronous!
|
| 3 | + |
| 4 | +## Why? |
| 5 | +Garry's Mod still doesn't have `file.AsyncWrite` function,. |
| 6 | +Also `file.AsyncRead` also [doesn't work properly in menu state][3], |
| 7 | +and Rubat doesn't want to elaborate in any way. |
| 8 | + |
| 9 | +Also [gm_async_write](https://github.com/WilliamVenner/gm_async_write) exists, |
| 10 | +but it doesn't provide binaries for client-side and doesn't have binaries for MacOS. |
| 11 | + |
| 12 | +## How to install? |
| 13 | +1. Go to [Releases][4] page |
| 14 | +2. Download binary that matches your OS and Garry's Mod branch |
| 15 | + * Select `gmsv_asyncio` binary if you need binary for your server |
| 16 | + or `gmcl_asyncio` if you need for clientside |
| 17 | + * Choose `asyncio_win`, `asyncio_linux` or `asyncio_osx` respectively to your OS |
| 18 | + * If you installed chromium or x86-64 Garry's Mod beta, then choose binary that ends with `win64.dll`/`linux64.dll`/`osx64.dll`, otherwise `win32.dll`/`linux.dll`/`osx.dll` |
| 19 | +3. Place freshly downloaded binary to `<Garry's Mod>/garrysmod/lua/bin/` folder |
| 20 | +4. Enjoy your smooth ride! |
| 21 | + |
| 22 | +## For Developers |
| 23 | +### API |
| 24 | +```lua |
| 25 | +-- Asynchronously writes given content to fileName in DATA folder |
| 26 | +-- Have same limitations as https://wiki.facepunch.com/gmod/file.Write |
| 27 | +-- Arguments: |
| 28 | +-- fileName: path to a file |
| 29 | +-- content: data to be written to a file |
| 30 | +-- callback: function that will be called when async operation finishes |
| 31 | +-- Arguments are: |
| 32 | +-- * fileName: string path to a file |
| 33 | +-- * gamePath: always "DATA" |
| 34 | +-- * status: see https://wiki.facepunch.com/gmod/Enums/FSASYNC |
| 35 | +-- Returns: |
| 36 | +-- status: FSASYNC_OK if successful, otherwise FSASYNC_ERR_ |
| 37 | +-- see https://wiki.facepunch.com/gmod/Enums/FSASYNC |
| 38 | +number asyncio.AsyncWrite( string fileName, string content, function callback ) |
| 39 | + |
| 40 | +-- Same as asyncio.AsyncWrite, but instead of rewriting content of the file, just appends content to file |
| 41 | +number asyncio.AsyncAppend( string fileName, string content, function callback ) |
| 42 | + |
| 43 | +-- Asynchronously reads content from a specified file |
| 44 | +-- Have same limitations as https://wiki.facepunch.com/gmod/file.Read |
| 45 | +-- Arguments: |
| 46 | +-- fileName: path to a file |
| 47 | +-- gamePath: see https://wiki.facepunch.com/gmod/File_Search_Paths |
| 48 | +-- callback: function that will be called when async operation finishes |
| 49 | +-- Arguments are: |
| 50 | +-- * fileName: string path to a file |
| 51 | +-- * gamePath: gamePath specified earlier |
| 52 | +-- * status: see https://wiki.facepunch.com/gmod/Enums/FSASYNC |
| 53 | +-- * data: contents of a file |
| 54 | +-- Returns: |
| 55 | +-- status: FSASYNC_OK if successful, otherwise FSASYNC_ERR_ |
| 56 | +-- see https://wiki.facepunch.com/gmod/Enums/FSASYNC |
| 57 | +number asyncio.AsyncRead( string fileName, string gamePath, function callback ) |
| 58 | + |
| 59 | +-- Good luck with coding! |
| 60 | +``` |
| 61 | + |
| 62 | +### Example |
| 63 | +```lua |
| 64 | +local data = "Hello World!" |
| 65 | + |
| 66 | +local ok = asyncio.AsyncWrite("example.txt", data, function(fileName, gamePath, status) |
| 67 | + local ok = asyncio.AsyncRead(filename, gamePath, function(fileName, gamePath, status, fileContent) |
| 68 | + print(status, status == FSASYNC_OK) -- 0 true |
| 69 | + print(fileContent) -- Hello World! |
| 70 | + print(data == fileContent) -- true |
| 71 | + end) |
| 72 | +end) |
| 73 | + |
| 74 | +print("Write successful:", ok == FSASYNC_OK) -- Write successful: true |
| 75 | +``` |
| 76 | + |
| 77 | +## Contributing |
| 78 | +Feel free to create issues and pull request ❤️ |
| 79 | + |
| 80 | +[1]: https://github.com/Pika-Software/gm_asyncio/actions/workflows/build.yml/badge.svg?branch=main |
| 81 | +[2]: https://github.com/Pika-Software/gm_asyncio/actions/workflows/build.yml |
| 82 | +[3]: https://github.com/Facepunch/garrysmod-issues/issues/5433 |
| 83 | +[4]: https://github.com/Pika-Software/gm_asyncio/releases |
0 commit comments