npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

node-filemap

v1.0.2

Published

Windows file mapping API for NodeJS

Downloads

11

Readme

node-filemap

Windows file mapping/shared memory node module.

I needed this API to mess with offscreen rendering in electron, but the only module I could find to do it was mmap-io, and I couldn't get it to work. So I decided to make a windows specific API, so people can use this on Windows and use that, or node-mmap on Linux operating systems.

Installation

You will need to have visual studio installed on your machine to build! I've only tested with VS 2017 Community, but it will probably work with other versions (No garunteees!). I know it will not work with VS 2012 or earlier, as I used a lot of C++ 11 features in the code.

It should install like any other package, and build the native components automatically:

npm install --save node-filemap

This library is windows only. If you want to run your app on other platforms, you can make it an optional install:

npm install --save-optional node-filemap

You will then have to deal with the package not being available on other systems in your code. You should look at mmap-io or node-mmap for that.

How to use

You should probably be familiar with how to use a the Win32 file mapping and mutex API's before using this. It's basically just a wrapper around those.

To create a file mapping object:

const {FileMapping} = require('./build/Release/addon');

map = new addon.FileMapping();
map.createMapping(
  'file.txt',        // Name of file (Can be null if you just want shared memory). If the file does not exist, it will be created.
  'my_mapped_file',  // Shared memory name (Cannot be null).
  20);               // Mapping size - How many bytes of the file to map into memory, or how large of a shared memory location to create.

buffer = Buffer.alloc(20)
map.readInto(
  0,         // What byte offset to start reading from
  20,        // How many bytes to read
  buffer);   // A buffer object to read into

console.log(buffer.ToString('utf8'));

FileMapping

FileMapping objects are used to manage file mappings and shared memory. Windows treats these two uses as nearly identical.

new FileMapping()

Constructs a new file mapping. You either need to call createMapping or openMapping to use it, until then it is just empty.

createMapping(file, name, size)

Creates a new file mapping.

file - The name of the file to map into memory. Can be null to just create shared memory.

name - The name of the shared memory location to make (For interprocess communication).

size - How large the memory location should be.

Returns nothing.

openMapping(name, size)

Opens an existing file mapping.

name - The name of the shared memory location/file mapping to open

size - The size of the memory location. Should be less than or equal to the size passed into createMapping.

Returns nothing.

closeMapping()

Closes the mapping. writeBuffer and readInto will no longer work once you do this. You should always call this when you are done with the file mapping. You can re-open the mapping after it is closed by calling createMapping or openMapping.

Returns nothing.

writeBuffer(buffer, destOffset, srcOffset, length)

Write a buffer into the file mapping

buffer - The buffer to write to the file mapping/shared memory.

destOffset - Where to start writing in the destination (The file mapping)

srcOffset - Where to start reading in the source (The buffer)

length - How many bytes to read from the buffer into the destination. This is not validated - Make sure you don't read off the end of the buffer or write off the end of the destination~

Returns nothing

readInto(offset, length, buffer)

Reads data from the file mapping into a buffer

offset The byte offset to start reading from in the file mapping

length The number of bytes to read

buffer The buffer to read into

Returns nothing

Mutex

I couldn't find a good interprocess mutex library for NodeJS on Windows (Microsoft has one but it doesn't support named Mutexes).

new Mutex

Just like new FileMap. Doesn't actually initialize the object - you need to call create or open to do that.

create(name)

Creates a named mutex

name - The name to give the mutex

Returns nothing

open(name)

Opens a named mutex that was previously created in another process

name - The name of the mutex to open

Returns nothing

close()

Closes the handle to this mutex. Always call this before ending your process.

wait([time])

Acquires this mutex

time - Optional. How long to wait for the lock to be granted. Defaults to INFINITE.

Returns WAIT_ABANDONED, WAIT_OBJECT_0, or WAIT_TIMEOUT. WAIT_OBJECT_0 means the lock was granted to your process. WAIT_TIMEOUT means that the time you passed in had elapsed without the lock being granted. WAIT_ABANDONED means the mutex was abandoned.

waitMultiple(mutexList, waitForAll, time)

Waits for multiple mutexes

mutexList - A list of all the mutexes you want to wait for.

waitForAll - true if you want to wait for every mutex in the list, false if you only want to wait for one.

time - Just like wait, how long to wait for the lock to be granted. Does not default to INFINITE, however.

Refer to MSDN for details on the return value.

FAQ

  • Why isn't this async? Nodejs is async. Because there's really no way to make this async, as far as I can tell.
  • Why not use mmap-io? Because it won't build on my machine ¯\_(ツ)_/¯
  • Why are all the names and parameters inconsistent? Because I programmed this in 5 hours. 3 of that was spent learning how to use shared memory in windows.
  • Why don't you support feature X of the windows API? Because I programmed this in 5 hours.

License