use types::c;

// Create an LMDB environment handle.
// 
// This function allocates memory for a [[env]] structure. To release
// the allocated memory and discard the handle, call [[env_close]].
// Before the handle may be used, it must be opened using [[env_open]].
// Various other options may also need to be set before opening the handle,
// e.g. [[env_set_mapsize]], [[env_set_maxreaders]], [[env_set_maxdbs]],
// depending on usage requirements.
//
// Parameters:
// - env: The address where the new handle will be stored
//
// Return value: A non-zero error value on failure and 0 on success.
export @symbol("mdb_env_create") fn env_create(env: nullable **env) int;

// Open an environment handle.
// 
// If this function fails, [[env_close]] must be called to discard the [[env]] handle.
// 
// Parameters:
// - env: An environment handle returned by [[env_create]]
// - path: The directory in which the database files reside. This
//   directory must already exist and be writable.
// - flags: Special options for this environment. This parameter
//   must be set to 0 or by bitwise OR'ing together one or more of the
//   values described here. Flags set by [[env_set_flags]] are also used.
// - mode: The UNIX permissions to set on created files and semaphores. This
//   parameter is ignored on Windows.
//
// - [[FIXEDMAP]]:
//		use a fixed address for the mmap region. This flag must be specified
//		when creating the environment, and is stored persistently in the environment.
//		If successful, the memory map will always reside at the same virtual address
//		and pointers used to reference data items in the database will be constant
//		across multiple invocations. This option may not always work, depending on
//		how the operating system has allocated memory to shared libraries and other uses.
//		The feature is highly experimental.
// - [[NOSUBDIR]]:
//		By default, LMDB creates its environment in a directory whose
//		pathname is given in \b path, and creates its data and lock files
//		under that directory. With this option, \b path is used as-is for
//		the database main data file. The database lock file is the \b path
//		with "-lock" appended.
// - [[RDONLY]]:
//		Open the environment in read-only mode. No write operations will be
//		allowed. LMDB will still modify the lock file - except on read-only
//		filesystems, where LMDB does not use locks.
// - [[WRITEMAP]]:
//		Use a writeable memory map unless MDB_RDONLY is set. This uses
//		fewer mallocs but loses protection from application bugs
//		like wild pointer writes and other bad updates into the database.
//		This may be slightly faster for DBs that fit entirely in RAM, but
//		is slower for DBs larger than RAM.
//		Incompatible with nested transactions.
//		Do not mix processes with and without MDB_WRITEMAP on the same
//		environment.  This can defeat durability (#mdb_env_sync etc).
// - [[NOMETASYNC]]:
//		Flush system buffers to disk only once per transaction, omit the
//		metadata flush. Defer that until the system flushes files to disk,
//		or next non-MDB_RDONLY commit or [[env_sync]]. This optimization
//		maintains database integrity, but a system crash may undo the last
//		committed transaction. I.e. it preserves the ACI (atomicity,
//		consistency, isolation) but not D (durability) database property.
//		This flag may be changed at any time using [[env_set_flags]].
// - [[NOSYNC]]:
//		Don't flush system buffers to disk when committing a transaction.
//		This optimization means a system crash can corrupt the database or
//		lose the last transactions if buffers are not yet flushed to disk.
//		The risk is governed by how often the system flushes dirty buffers
//		to disk and how often [[env_sync]] is called.  However, if the
//		filesystem preserves write order and the [[WRITEMAP]] flag is not
//		used, transactions exhibit ACI (atomicity, consistency, isolation)
//		properties and only lose D (durability).  I.e. database integrity
//		is maintained, but a system crash may undo the final transactions.
//		Note that ([[NOSYNC]] | [[WRITEMAP)]] leaves the system with no
//		hint for when to write transactions to disk, unless [[env_sync]]
//		is called. ([[MAPASYNC]] | [[WRITEMAP)]] may be preferable.
//		This flag may be changed at any time using [[env_set_flags]].
// - [[MAPASYNC]]:
//		When using [[WRITEMAP]], use asynchronous flushes to disk.
//		As with [[NOSYNC]], a system crash can then corrupt the
//		database or lose the last transactions. Calling [[env_sync]]
//		ensures on-disk database integrity until next commit.
//		This flag may be changed at any time using [[env_set_flags]].
// - [[NOTLS]]:
//		Don't use Thread-Local Storage. Tie reader locktable slots to
//		[[txn]] objects instead of to threads. I.e. [[txn_reset]] keeps
//		the slot reserved for the [[txn]] object. A thread may use parallel
//		read-only transactions. A read-only transaction may span threads if
//		the user synchronizes its use. Applications that multiplex many
//		user threads over individual OS threads need this option. Such an
//		application must also serialize the write transactions in an OS
//		thread, since LMDB's write locking is unaware of the user threads.
// - [[NOLOCK]]:
//		Don't do any locking. If concurrent access is anticipated, the
//		caller must manage all concurrency itself. For proper operation
//		the caller must enforce single-writer semantics, and must ensure
//		that no readers are using old transactions while a writer is
//		active. The simplest approach is to use an exclusive lock so that
//		no readers may be active at all when a writer begins.
// - [[NORDAHEAD]]:
//		Turn off readahead. Most operating systems perform readahead on
//		read requests by default. This option turns it off if the OS
//		supports it. Turning it off may help random read performance
//		when the DB is larger than RAM and system RAM is full.
//		The option is not implemented on Windows.
// - [[NOMEMINIT]]:
//		Don't initialize malloc'd memory before writing to unused spaces
//		in the data file. By default, memory for pages written to the data
//		file is obtained using malloc. While these pages may be reused in
//		subsequent transactions, freshly malloc'd pages will be initialized
//		to zeroes before use. This avoids persisting leftover data from other
//		code (that used the heap and subsequently freed the memory) into the
//		data file. Note that many other system libraries may allocate
//		and free memory from the heap for arbitrary uses. E.g., stdio may
//		use the heap for file I/O buffers. This initialization step has a
//		modest performance cost so some applications may want to disable
//		it using this flag. This option can be a problem for applications
//		which handle sensitive data like passwords, and it makes memory
//		checkers like Valgrind noisy. This flag is not needed with [[WRITEMAP]],
//		which writes directly to the mmap instead of using malloc for pages. The
//		initialization is also skipped if [[RESERVE]] is used; the
//		caller is expected to overwrite all of the memory that was
//		reserved in that case.
//		This flag may be changed at any time using [[env_set_flags]].
//
// Return value: A non-zero error value on failure and 0 on success. Some possible
// errors are:
// - [[VERSION_MISMATCH]] - the version of the LMDB library doesn't match the
//   version that created the database environment.
// - [[INVALID]] - the environment file headers are corrupted.
// - ENOENT - the directory specified by the path parameter doesn't exist.
// - EACCES - the user didn't have permission to access the environment files.
// - EAGAIN - the environment was locked by another process.
export @symbol("mdb_env_open") fn env_open(env: *env, path: const *c::char, flag: uint, mode: mode_t) int;

// Close the environment and release the memory map.
// 
// Only a single thread may call this function. All transactions, databases,
// and cursors must already be closed before calling this function. Attempts to
// use any such handles after calling this function will cause a SIGSEGV.
// The environment handle will be freed and must not be used again after this call.
//
// Parameters:
// - env: An environment handle returned by [[env_create]]
export @symbol("mdb_env_close") fn env_close(env: *env) void;