# FIXME cannot do placement alloc of private types
type File = private

func create_atomic(rwref File base, ref String filename) alloc File
func create_shared(rwref File base, ref String filename) alloc File
func open_read(rwref File base, ref String filename) alloc File
func open_append(rwref File base, ref String filename) alloc File
func open_overwrite(rwref File base, ref String filename) alloc File
func open_readwrite(rwref File base, ref String filename) alloc File

func close(rwref File file)
func close_free(dealloc rwref File file)
func flush_async(rwref File file)
func flush_sync(rwref File file)
func sync(rwref File file) returns SomeKindOfStatus

# for files created with create_atomic
func close_commit(dealloc rwref File file)
func close_cancel(dealloc rwref File file)
func commit(rwref File file)

func read_async(offset offs, size length)
# can we prevent the caller from modifying the data during the write operation?
# needs a new "takeown" keyword? because we want to allow "data" to be on the stack
func write_async(offset offs, size length, ref [length]byte data)