src/core/koa.c File Reference

KOA manager implementation. More...

#include <sys/types.h>
#include <sys/stat.h>
#include <libc/syscalls.h>
#include <misc/malloc.h>
#include <misc/result.h>
#include <misc/debug.h>
#include <misc/pool.h>
#include <misc/hash_table.h>
#include <misc/mutex.h>
#include <core/config.h>
#include <core/koa.h>
#include <core/sentinel.h>
#include <core/buffer.h>
#include <stdlib.h>
#include <pthread.h>
#include <stddef.h>

Go to the source code of this file.

Classes
struct	txc_koa_file_s
struct	txc_koa_sock_dgram_s
struct	txc_koa_pipe_read_end_s
struct	txc_koa_s
struct	txc_fd2koa_s
struct	txc_alias_cache_s
struct	txc_koamgr_s
Typedefs
typedef txc_koa_file_s	txc_koa_file_t
typedef txc_koa_sock_dgram_s	txc_koa_sock_dgram_t
typedef txc_koa_pipe_read_end_s	txc_koa_pipe_read_end_t
typedef txc_fd2koa_s	txc_fd2koa_t
typedef txc_alias_cache_s	txc_alias_cache_t
Functions
txc_result_t	txc_koamgr_create (txc_koamgr_t **koamgrp, txc_sentinelmgr_t *sentinelmgr, txc_buffermgr_t *buffermgr)
	Creates a KOA manager.
void	txc_koamgr_destroy (txc_koamgr_t **koamgrp)
	Destroys a KOA manager.
txc_result_t	txc_koa_lock_alias_cache (txc_koamgr_t *koamgr)
	Locks the alias cache's serialization mutex.
txc_result_t	txc_koa_unlock_alias_cache (txc_koamgr_t *koamgr)
	Unlocks the alias cache's serialization mutex.
txc_result_t	txc_koa_alias_cache_lookup_inode (txc_koamgr_t *koamgr, ino_t inode_number, txc_koa_t **koap)
	Looks up the alias cache for a file KOA.
txc_result_t	txc_koa_create (txc_koamgr_t *koamgr, txc_koa_t **koap, int type, void *args)
	Creates a KOA.
void	txc_koa_destroy (txc_koa_t **koap)
	Destroy a KOA.
txc_result_t	txc_koa_attach_fd (txc_koa_t *koa, int fd, int lock)
	Attach a file descriptor to a KOA.
txc_result_t	txc_koa_detach_fd (txc_koa_t *koa, int fd, int lock)
	Detach a file descriptor from a KOA.
txc_result_t	txc_koa_lookup_fd2koa (txc_koamgr_t *koamgr, int fd, txc_koa_t **koap)
	Finds the KOA the file descriptor is mapped to.
txc_result_t	txc_koa_lock_fd (txc_koamgr_t *koamgr, int fd)
	Locks a file descriptor.
txc_result_t	txc_koa_unlock_fd (txc_koamgr_t *koamgr, int fd)
	Unlocks a file descriptor.
txc_result_t	txc_koa_lock_fds_refby_koa (txc_koa_t *koa)
	Locks all the file descriptors mapped to a KOA.
txc_result_t	txc_koa_unlock_fds_refby_koa (txc_koa_t *koa)
	Unlocks all the file descriptors mapped to a KOA.
txc_result_t	txc_koa_path2inode (const char *path, ino_t *inode_number)
	Finds the inode of the file pointed by path.
txc_result_t	txc_koa_attach (txc_koa_t *koa)
	Attaches to a KOA.
txc_result_t	txc_koa_detach (txc_koa_t *koa)
	Detaches from a KOA.
txc_sentinel_t *	txc_koa_get_sentinel (txc_koa_t *koa)
txc_koamgr_t *	txc_koa_get_koamgr (txc_koa_t *koa)
void *	txc_koa_get_buffer (txc_koa_t *koa)
Variables
txc_koamgr_t *	txc_g_koamgr

---

Detailed Description

KOA manager implementation.

A KOA (Kernel Object Abstraction) is the user-mode representation of a logical kernel object. It is used for serializing accesses to the kernel object (via sentinel) and for bufferring uncommitted state (buffer).

As shown in the figure below, all KOAs are accessible through the file descriptor to KOA map. Additionally, file KOAs are accessible through the alias cache's hash table by indexing the table using the file's inode.

Alias cache and file descriptor to KOA map.

Locking Protocol

There are three types of locks of interest:

• Alias cache serialization lock: Serializes directory operations (open, create, rename, unlink) and any KOA creation/destruction caused by these operations.
• FD2KOA mutex lock: Synchronizes accesses to KOA through a file descriptor. Holding this lock ensures that a KOA does not disappear after following a valid reference through a file descriptor. This is because a KOA cannot be destroyed without holding locks on all the file descriptors referencing the KOA.
• KOA mutex lock: Synchronizes KOA accesses when not holding the alias or file descriptor lock. This can happen when deattaching from a KOA/sentinel when a transaction commits/aborts.

  Todo:

  This lock might be unnecessary.

  More on file descriptor locks
• Operations that use a file descriptor don't acquire the KOA cache lock
• Operations on file descriptors acquire a short lock on the FD to properly synchronize accesses to metadata. They don't acquire the alias lock.
• Operations that operate on pathnames must ensure they are correctly sycnhronized with operations on FDs. So they need to acquire a short lock on all FDs referenced by a KOA. Operations such as copy require this isolation. But operations such as unlink could rely on UNIX semantics for isolation.
• Operations such as opening an existing file that has a KOA in the alias cache must acquire the locks on all the file descriptors referencing the file to properly synchronize with writes/reads when accessing the metadata.

Todo:

Relax aliasing in favor of concurrency.

Definition in file koa.c.

---

Function Documentation

txc_result_t txc_koa_alias_cache_lookup_inode	(	txc_koamgr_t *	koamgr,
		ino_t	inode_number,
		txc_koa_t **	koap
	)

Looks up the alias cache for a file KOA.

Parameters:

[in]	koamgr	Alias cache's KOA manager.
[in]	inode_number	Inode number of the file to lookup.
[out]	koap	Pointer to the KOA if file has been found in the alias cache.

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 327 of file koa.c.

References txc_koamgr_s::alias_cache, txc_alias_cache_s::hash_tbl, txc_hash_table_lookup(), TXC_R_NOTEXISTS, and TXC_R_SUCCESS.

Referenced by x_create(), x_open(), x_rename(), and x_unlink().

txc_result_t txc_koa_attach

(

txc_koa_t *

koa

)

Attaches to a KOA.

Logically attaches to a KOA by incrementing the KOA's reference counter by one.

Parameters:

[in]

koa

The KOA to attach to.

Returns:

Code indicating success or failure (reason) of the operation.

If this is the first attach, then insert KOA into the alias cache if it is an aliasable KOA (e.g. file).

Definition at line 696 of file koa.c.

References txc_koa_s::manager, txc_koa_s::mutex, txc_koa_s::refcnt, txc_koa_s::sentinel, TXC_ASSERT, TXC_DEBUG_KOA, TXC_DEBUG_PRINT, TXC_KOA_IS_FILE, TXC_MUTEX_LOCK, TXC_MUTEX_UNLOCK, TXC_R_SUCCESS, and txc_koa_s::type.

Referenced by x_rename(), and x_unlink().

txc_result_t txc_koa_attach_fd	(	txc_koa_t *	koa,
		int	fd,
		int	lock
	)

Attach a file descriptor to a KOA.

Parameters:

[in]	koa	The KOA the file descriptor is attached to.
[in]	fd	The file descriptor attached to KOA.
[in]	lock	If set then this function acquires the lock on the file descriptor

Returns:

Code indicating success or failure (reason) of the operation.

First attach -- insert it into the alias cache if aliasable KOA.

Definition at line 446 of file koa.c.

References txc_koa_s::fd, txc_koa_s::fdref, txc_fd2koa_s::koa, txc_koa_s::manager, txc_koamgr_s::map, txc_fd2koa_s::mutex, txc_koa_s::refcnt, txc_koa_s::sentinel, TXC_ASSERT, TXC_DEBUG_KOA, TXC_DEBUG_PRINT, TXC_INTERNALERROR, TXC_KOA_IS_FILE, TXC_KOA_MAP_SIZE, TXC_MAX_NUM_FDREFS_PER_KOA, TXC_MUTEX_LOCK, TXC_MUTEX_UNLOCK, TXC_R_SUCCESS, and txc_koa_s::type.

Referenced by txc_koamgr_create(), x_create(), x_dup(), x_open(), x_pipe(), and x_socket().

txc_result_t txc_koa_create	(	txc_koamgr_t *	koamgr,
		txc_koa_t **	koap,
		int	type,
		void *	args
	)

Creates a KOA.

Parameters:

[in]	koamgr	The KOA manager creating and managing the KOA.
[out]	koap	Pointer to the created KOA.
[in]	type	Type of the KOA to be created: TXC_KOA_IS_FILE, TXC_KOA_IS_SOCK_DGRAM, TXC_KOA_IS_PIPE_READ_END
[in]	args	Arguments specific to the type of KOA created. For file KOA this is the inode of the file.

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 358 of file koa.c.

References txc_koamgr_s::pool_koa_obj, txc_sentinel_s::refcnt, txc_koamgr_s::sentinelmgr, txc_buffer_circular_create(), TXC_INTERNALERROR, TXC_KOA_IS_FILE, TXC_KOA_IS_PIPE_READ_END, TXC_KOA_IS_SOCK_DGRAM, TXC_MUTEX_INIT, txc_pool_object_alloc(), TXC_R_SUCCESS, and txc_sentinel_create().

Referenced by txc_koamgr_create(), x_create(), x_open(), x_pipe(), x_rename(), x_socket(), and x_unlink().

void txc_koa_destroy

(

txc_koa_t **

koap

)

Destroy a KOA.

Parameters:

[in,out]

Pointer

to the KOA to be destroyed.

Definition at line 410 of file koa.c.

References txc_buffer_circular_destroy(), TXC_KOA_IS_FILE, TXC_KOA_IS_PIPE_READ_END, TXC_KOA_IS_SOCK_DGRAM, txc_pool_object_free(), and txc_sentinel_detach().

Referenced by txc_koa_detach().

txc_result_t txc_koa_detach

(

txc_koa_t *

koa

)

Detaches from a KOA.

It logically detaches from a KOA by decrementing the KOA's reference counter by one. It destroys a KOA after detach if reference counter gets zero.

Parameters:

[in]

koa

The KOA to detach from.

Returns:

Code indicating success or failure (reason) of the operation.

Last detach -- remove it from the alias cache if aliasable KOA.

Definition at line 737 of file koa.c.

References txc_koa_s::manager, txc_koa_s::mutex, txc_koa_s::refcnt, txc_koa_s::sentinel, TXC_ASSERT, TXC_DEBUG_KOA, TXC_DEBUG_PRINT, txc_koa_destroy(), TXC_KOA_IS_FILE, TXC_MUTEX_LOCK, TXC_MUTEX_UNLOCK, TXC_R_SUCCESS, and txc_koa_s::type.

Referenced by x_rename(), and x_unlink().

txc_result_t txc_koa_detach_fd	(	txc_koa_t *	koa,
		int	fd,
		int	lock
	)

Detach a file descriptor from a KOA.

Parameters:

[in]	koa	The KOA the file descriptor is detached from.
[in]	fd	The file descriptor detached from KOA.
[in]	lock	If set then this function acquires the lock on the file descriptor

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 496 of file koa.c.

References txc_koa_s::fd, txc_koa_s::fdref, txc_fd2koa_s::koa, txc_koa_s::manager, txc_koamgr_s::map, txc_fd2koa_s::mutex, txc_koa_s::refcnt, TXC_ASSERT, TXC_KOA_MAP_SIZE, TXC_MUTEX_LOCK, and TXC_R_FAILURE.

Referenced by x_close(), and x_open().

void* txc_koa_get_buffer

(

txc_koa_t *

koa

)

Gets the buffer of a KOA.

Parameters:

[in]

koa

The KOA of which to get the sentinel.

Returns:

The buffer of the KOA.

Definition at line 798 of file koa.c.

References txc_koa_sock_dgram_s::buffer_circular_input, txc_koa_pipe_read_end_s::buffer_circular_input, txc_koa_s::pipe_read_end, txc_koa_s::sock_dgram, TXC_KOA_IS_PIPE_READ_END, TXC_KOA_IS_SOCK_DGRAM, and txc_koa_s::type.

txc_koamgr_t* txc_koa_get_koamgr

(

txc_koa_t *

koa

)

Gets the KOA manager of a KOA.

Parameters:

[in]

koa

The KOA of which to get the sentinel.

Returns:

The KOA manager of the KOA.

Definition at line 785 of file koa.c.

References txc_koa_s::manager.

txc_sentinel_t* txc_koa_get_sentinel

(

txc_koa_t *

koa

)

Gets the sentinel of a KOA.

Parameters:

[in]

koa

The KOA of which to get the sentinel.

Returns:

The sentinel of the KOA.

Definition at line 772 of file koa.c.

References txc_koa_s::sentinel.

Referenced by x_close(), x_create(), x_dup(), x_fsync(), x_lseek(), x_open(), x_pipe(), x_read(), x_rename(), x_sendmsg(), x_socket(), x_unlink(), and x_write_pipe().

txc_result_t txc_koa_lock_alias_cache

(

txc_koamgr_t *

koamgr

)

Locks the alias cache's serialization mutex.

Parameters:

[in]

koamgr

KOA manager.

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 243 of file koa.c.

References txc_koamgr_s::alias_cache, txc_alias_cache_s::mutex, TXC_MUTEX_LOCK, and TXC_R_SUCCESS.

Referenced by x_close(), x_create(), x_open(), x_rename(), and x_unlink().

txc_result_t txc_koa_lock_fd	(	txc_koamgr_t *	koamgr,
		int	fd
	)

Locks a file descriptor.

Parameters:

[in]	koamgr	KOA manager.
[in]	File	descriptor to lock.

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 582 of file koa.c.

References txc_koamgr_s::map, txc_fd2koa_s::mutex, TXC_MUTEX_LOCK, TXC_R_FAILURE, and TXC_R_SUCCESS.

Referenced by x_close(), x_create(), x_dup(), x_fsync(), x_lseek(), x_open(), x_pipe(), x_read(), x_sendmsg(), x_socket(), and x_write_pipe().

txc_result_t txc_koa_lock_fds_refby_koa

(

txc_koa_t *

koa

)

Locks all the file descriptors mapped to a KOA.

Parameters:

[in]

koa

The KOA of which to lock the file descriptors.

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 617 of file koa.c.

References txc_koa_s::fd, txc_koa_s::fdref, txc_koa_s::manager, txc_koamgr_s::map, txc_fd2koa_s::mutex, txc_koa_s::refcnt, TXC_MUTEX_LOCK, and TXC_R_SUCCESS.

Referenced by x_create(), x_dup(), x_open(), x_rename(), and x_unlink().

txc_result_t txc_koa_lookup_fd2koa	(	txc_koamgr_t *	koamgr,
		int	fd,
		txc_koa_t **	koap
	)

Finds the KOA the file descriptor is mapped to.

Parameters:

[in]	koamgr	KOA manager.
[in]	fd	File descriptor.
[out]	koap	Pointer to the KOA the file descriptor is mapped to.

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 563 of file koa.c.

References txc_fd2koa_s::koa, txc_koamgr_s::map, TXC_ASSERT, TXC_KOA_MAP_SIZE, TXC_R_FAILURE, and TXC_R_SUCCESS.

Referenced by x_close(), x_dup(), x_fsync(), x_lseek(), x_read(), x_sendmsg(), and x_write_pipe().

txc_result_t txc_koa_path2inode	(	const char *	path,
		ino_t *	inode_number
	)

Finds the inode of the file pointed by path.

Parameters:

[in]	path	The pathanme of the file to look for.
[out]	inode_number	The inode of the file.

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 670 of file koa.c.

References TXC_R_SUCCESS.

Referenced by x_create(), x_open(), x_rename(), and x_unlink().

txc_result_t txc_koa_unlock_alias_cache

(

txc_koamgr_t *

koamgr

)

Unlocks the alias cache's serialization mutex.

Parameters:

[in]

koamgr

KOA manager.

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 257 of file koa.c.

References txc_koamgr_s::alias_cache, txc_alias_cache_s::mutex, TXC_MUTEX_UNLOCK, and TXC_R_SUCCESS.

Referenced by x_close(), x_create(), x_open(), x_rename(), and x_unlink().

txc_result_t txc_koa_unlock_fd	(	txc_koamgr_t *	koamgr,
		int	fd
	)

Unlocks a file descriptor.

Parameters:

[in]	koamgr	KOA manager.
[in]	File	descriptor to unlock.

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 600 of file koa.c.

References txc_koamgr_s::map, txc_fd2koa_s::mutex, TXC_MUTEX_UNLOCK, TXC_R_FAILURE, and TXC_R_SUCCESS.

Referenced by x_close(), x_create(), x_dup(), x_fsync(), x_lseek(), x_open(), x_pipe(), x_read(), x_sendmsg(), x_socket(), and x_write_pipe().

txc_result_t txc_koa_unlock_fds_refby_koa

(

txc_koa_t *

koa

)

Unlocks all the file descriptors mapped to a KOA.

Parameters:

[in]

koa

The KOA of which to unlock the file descriptors.

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 646 of file koa.c.

References txc_koa_s::fd, txc_koa_s::fdref, txc_koa_s::manager, txc_koamgr_s::map, txc_fd2koa_s::mutex, txc_koa_s::refcnt, TXC_MUTEX_UNLOCK, and TXC_R_SUCCESS.

Referenced by x_create(), x_dup(), x_open(), x_rename(), and x_unlink().

txc_result_t txc_koamgr_create	(	txc_koamgr_t **	koamgrp,
		txc_sentinelmgr_t *	sentinelmgr,
		txc_buffermgr_t *	buffermgr
	)

Creates a KOA manager.

It creates a pool of KOAs and an alias cache for file KOAs. It also precreates pipe KOAs for standard input, output, error.

Parameters:

[out]	koamgrp	Pointer to the create manager.
[in]	sentinelmgr	The sentinel manager backing this manager's KOAs with sentinels.
[in]	buffermgr	The buffer manager backing this manager's KOAs with buffers.

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 170 of file koa.c.

References FREE, MALLOC, txc_hash_table_create(), txc_koa_attach_fd(), TXC_KOA_CACHE_HASHTBL_SIZE, txc_koa_create(), TXC_KOA_IS_PIPE_READ_END, TXC_KOA_IS_PIPE_WRITE_END, TXC_KOA_MAP_SIZE, TXC_KOA_NUM, TXC_MUTEX_INIT, txc_pool_create(), txc_pool_destroy(), TXC_R_NOMEMORY, and TXC_R_SUCCESS.

Referenced by _TXC_global_init().

void txc_koamgr_destroy

(

txc_koamgr_t **

koamgrp

)

Destroys a KOA manager.

Parameters:

[in,out]

koamgrp

A pointer to the KOA manager to be destroyed.

Returns:

Code indicating success or failure (reason) of the operation.

Definition at line 227 of file koa.c.

References FREE, txc_hash_table_destroy(), and txc_pool_destroy().

---