lib/libblockdriver/driver_mt.c

/* This file contains the multithreaded driver interface.
 *
 * Changes:
 *   Aug 27, 2011   created (A. Welzel)
 *
 * The entry points into this file are:
 *   blockdriver_mt_task:	the main message loop of the driver
 *   blockdriver_mt_terminate:	break out of the main message loop
 *   blockdriver_mt_sleep:	put the current thread to sleep
 *   blockdriver_mt_wakeup:	wake up a sleeping thread
 *   blockdriver_mt_set_workers:set the number of worker threads
 */

#include <minix/blockdriver_mt.h>
#include <minix/mthread.h>
#include <assert.h>

#include "const.h"
#include "driver.h"
#include "driver_mt.h"
#include "mq.h"

/* A thread ID is composed of a device ID and a per-device worker thread ID.
 * All thread IDs must be in the range 0..(MAX_THREADS-1) inclusive.
 */
#define MAKE_TID(did, wid)	((did) * MAX_WORKERS + (wid))
#define TID_DEVICE(tid)		((tid) / MAX_WORKERS)
#define TID_WORKER(tid)		((tid) % MAX_WORKERS)

typedef unsigned int worker_id_t;

typedef enum {
  STATE_DEAD,
  STATE_RUNNING,
  STATE_BUSY,
  STATE_EXITED
} worker_state;

/* Structure with information about a worker thread. */
typedef struct {
  device_id_t device_id;
  worker_id_t worker_id;
  worker_state state;
  mthread_thread_t mthread;
  mthread_event_t sleep_event;
} worker_t;

/* Structure with information about a device. */
typedef struct {
  device_id_t id;
  unsigned int workers;
  worker_t worker[MAX_WORKERS];
  mthread_event_t queue_event;
  mthread_rwlock_t barrier;
} device_t;

static struct blockdriver *bdtab;
static int running = FALSE;

static mthread_key_t worker_key;

static device_t device[MAX_DEVICES];

static worker_t *exited[MAX_THREADS];
static int num_exited = 0;

/*===========================================================================*
 *				enqueue					     *
 *===========================================================================*/
static void enqueue(device_t *dp, const message *m_src, int ipc_status)
{
/* Enqueue a message into the device's queue, and signal the event.
 * Must be called from the master thread.
 */

  if (!mq_enqueue(dp->id, m_src, ipc_status))
	panic("blockdriver_mt: enqueue failed (message queue full)");

  mthread_event_fire(&dp->queue_event);
}

/*===========================================================================*
 *				try_dequeue				     *
 *===========================================================================*/
static int try_dequeue(device_t *dp, message *m_dst, int *ipc_status)
{
/* See if a message can be dequeued from the current worker thread's device
 * queue. If so, dequeue the message and return TRUE. If not, return FALSE.
 * Must be called from a worker thread. Does not block.
 */

  return mq_dequeue(dp->id, m_dst, ipc_status);
}

/*===========================================================================*
 *				dequeue					     *
 *===========================================================================*/
static int dequeue(device_t *dp, worker_t *wp, message *m_dst,
  int *ipc_status)
{
/* Dequeue a message from the current worker thread's device queue. Block the
 * current thread if necessary. Must be called from a worker thread. Either
 * succeeds with a message (TRUE) or indicates that the thread should be
 * terminated (FALSE).
 */

  do {
	mthread_event_wait(&dp->queue_event);

	/* If we were woken up as a result of terminate or set_workers, break
	 * out of the loop and terminate the thread.
	 */
	if (!running || wp->worker_id >= dp->workers)
		return FALSE;
  } while (!try_dequeue(dp, m_dst, ipc_status));

  return TRUE;
}

/*===========================================================================*
 *				is_transfer_req				     *
 *===========================================================================*/
static int is_transfer_req(int type)
{
/* Return whether the given block device request is a transfer request.
 */

  switch (type) {
  case BDEV_READ:
  case BDEV_WRITE:
  case BDEV_GATHER:
  case BDEV_SCATTER:
	return TRUE;

  default:
	return FALSE;
  }
}

/*===========================================================================*
 *				worker_thread				     *
 *===========================================================================*/
static void *worker_thread(void *param)
{
/* The worker thread loop. Set up the thread-specific reference to itself and
 * start looping. The loop consists of blocking dequeing and handling messages.
 * After handling a message, the thread might have been stopped, so we check
 * for this condition and exit if so.
 */
  worker_t *wp;
  device_t *dp;
  thread_id_t tid;
  message m;
  int ipc_status;

  wp = (worker_t *) param;
  assert(wp != NULL);
  dp = &device[wp->device_id];
  tid = MAKE_TID(wp->device_id, wp->worker_id);

  if (mthread_setspecific(worker_key, wp))
	panic("blockdriver_mt: could not save local thread pointer");

  while (running && wp->worker_id < dp->workers) {

	/* See if a new message is available right away. */
	if (!try_dequeue(dp, &m, &ipc_status)) {

		/* If not, block waiting for a new message or a thread
		 * termination event.
		 */
		if (!dequeue(dp, wp, &m, &ipc_status))
			break;
	}

	/* Even if the thread was stopped before, a new message resumes it. */
	wp->state = STATE_BUSY;

	/* If the request is a transfer request, we acquire the read barrier
	 * lock. Otherwise, we acquire the write lock.
	 */
	if (is_transfer_req(m.m_type))
		mthread_rwlock_rdlock(&dp->barrier);
	else
		mthread_rwlock_wrlock(&dp->barrier);

	/* Handle the request and send a reply. */
	blockdriver_process_on_thread(bdtab, &m, ipc_status, tid);

	/* Switch the thread back to running state, and unlock the barrier. */
	wp->state = STATE_RUNNING;
	mthread_rwlock_unlock(&dp->barrier);
  }

  /* Clean up and terminate this thread. */
  if (mthread_setspecific(worker_key, NULL))
	panic("blockdriver_mt: could not delete local thread pointer");

  wp->state = STATE_EXITED;

  exited[num_exited++] = wp;

  return NULL;
}

/*===========================================================================*
 *				master_create_worker			     *
 *===========================================================================*/
static void master_create_worker(worker_t *wp, worker_id_t worker_id,
  device_id_t device_id)
{
/* Start a new worker thread.
 */
  mthread_attr_t attr;
  int r;

  wp->device_id = device_id;
  wp->worker_id = worker_id;
  wp->state = STATE_RUNNING;

  /* Initialize synchronization primitives. */
  mthread_event_init(&wp->sleep_event);

  r = mthread_attr_init(&attr);
  if (r != 0)
	panic("blockdriver_mt: could not initialize attributes (%d)", r);

  r = mthread_attr_setstacksize(&attr, STACK_SIZE);
  if (r != 0)
	panic("blockdriver_mt: could not set stack size (%d)", r);

  r = mthread_create(&wp->mthread, &attr, worker_thread, (void *) wp);
  if (r != 0)
	panic("blockdriver_mt: could not start thread %d (%d)", worker_id, r);

  mthread_attr_destroy(&attr);
}

/*===========================================================================*
 *				master_destroy_worker			     *
 *===========================================================================*/
static void master_destroy_worker(worker_t *wp)
{
/* Clean up resources used by an exited worker thread.
 */

  assert(wp != NULL);
  assert(wp->state == STATE_EXITED);

  /* Join the thread. */
  if (mthread_join(wp->mthread, NULL))
	panic("blockdriver_mt: could not join thread %d", wp->worker_id);

  /* Destroy resources. */
  mthread_event_destroy(&wp->sleep_event);

  wp->state = STATE_DEAD;
}

/*===========================================================================*
 *				master_handle_exits			     *
 *===========================================================================*/
static void master_handle_exits(void)
{
/* Destroy the remains of all exited threads.
 */
  int i;

  for (i = 0; i < num_exited; i++)
	master_destroy_worker(exited[i]);

  num_exited = 0;
}

/*===========================================================================*
 *				master_yield				     *
 *===========================================================================*/
static void master_yield(void)
{
/* Let worker threads run, and clean up any exited threads.
 */

  mthread_yield_all();

  if (num_exited > 0)
	master_handle_exits();
}

/*===========================================================================*
 *				master_handle_message			     *
 *===========================================================================*/
static void master_handle_message(message *m_ptr, int ipc_status)
{
/* For real request messages, query the device ID, start a thread if none is
 * free and the maximum number of threads for that device has not yet been
 * reached, and enqueue the message in the devices's message queue. All other
 * messages are handled immediately from the main thread.
 */
  device_id_t id;
  worker_t *wp;
  device_t *dp;
  unsigned int wid;
  int r;

  /* If this is not a block driver request, we cannot get the minor device
   * associated with it, and thus we can not tell which thread should process
   * it either. In that case, the master thread has to handle it instead.
   */
  if (is_ipc_notify(ipc_status) || !IS_BDEV_RQ(m_ptr->m_type)) {
	/* Process as 'other' message. */
	blockdriver_process_on_thread(bdtab, m_ptr, ipc_status, MAIN_THREAD);

	return;
  }

  /* Query the device ID. Upon failure, send the error code to the caller. */
  r = (*bdtab->bdr_device)(m_ptr->m_lbdev_lblockdriver_msg.minor, &id);
  if (r != OK) {
	blockdriver_reply(m_ptr, ipc_status, r);

	return;
  }

  /* Look up the device control block. */
  assert(id >= 0 && id < MAX_DEVICES);
  dp = &device[id];

  /* Find the first non-busy worker thread. */
  for (wid = 0; wid < dp->workers; wid++)
	if (dp->worker[wid].state != STATE_BUSY)
		break;

  /* If the worker thread is dead, start a thread now, unless we have already
   * reached the maximum number of threads.
   */
  if (wid < dp->workers) {
	wp = &dp->worker[wid];

	assert(wp->state != STATE_EXITED);

	/* If the non-busy thread has not yet been created, create one now. */
	if (wp->state == STATE_DEAD)
		master_create_worker(wp, wid, dp->id);
  }

  /* Enqueue the message at the device queue. */
  enqueue(dp, m_ptr, ipc_status);
}

/*===========================================================================*
 *				master_init				     *
 *===========================================================================*/
static void master_init(struct blockdriver *bdp)
{
/* Initialize the state of the master thread.
 */
  int i, j;

  assert(bdp != NULL);
  assert(bdp->bdr_device != NULL);

  bdtab = bdp;

  /* Initialize device-specific data structures. */
  for (i = 0; i < MAX_DEVICES; i++) {
	device[i].id = i;
	device[i].workers = 1;
	mthread_event_init(&device[i].queue_event);
	mthread_rwlock_init(&device[i].barrier);

	for (j = 0; j < MAX_WORKERS; j++)
		device[i].worker[j].state = STATE_DEAD;
  }

  /* Initialize a per-thread key, where each worker thread stores its own
   * reference to the worker structure.
   */
  if (mthread_key_create(&worker_key, NULL))
	panic("blockdriver_mt: error initializing worker key");
}

/*===========================================================================*
 *				blockdriver_mt_get_tid			     *
 *===========================================================================*/
thread_id_t blockdriver_mt_get_tid(void)
{
/* Return back the ID of this thread.
 */
  worker_t *wp;

  wp = (worker_t *) mthread_getspecific(worker_key);

  if (wp == NULL)
	panic("blockdriver_mt: master thread cannot query thread ID\n");

  return MAKE_TID(wp->device_id, wp->worker_id);
}

/*===========================================================================*
 *				blockdriver_mt_receive			     *
 *===========================================================================*/
static void blockdriver_mt_receive(message *m_ptr, int *ipc_status)
{
/* Receive a message.
 */
  int r;

  r = sef_receive_status(ANY, m_ptr, ipc_status);

  if (r != OK)
	panic("blockdriver_mt: sef_receive_status() returned %d", r);
}

/*===========================================================================*
 *				blockdriver_mt_task			     *
 *===========================================================================*/
void blockdriver_mt_task(struct blockdriver *driver_tab)
{
/* The multithreaded driver task.
 */
  int ipc_status, i;
  message mess;

  /* Initialize first if necessary. */
  if (!running) {
	master_init(driver_tab);

	running = TRUE;
  }

  /* The main message loop. */
  while (running) {
	/* Receive a message. */
	blockdriver_mt_receive(&mess, &ipc_status);

	/* Dispatch the message. */
	master_handle_message(&mess, ipc_status);

	/* Let worker threads run. */
	master_yield();
  }

  /* Free up resources. */
  for (i = 0; i < MAX_DEVICES; i++)
	mthread_event_destroy(&device[i].queue_event);
}

/*===========================================================================*
 *				blockdriver_mt_terminate		     *
 *===========================================================================*/
void blockdriver_mt_terminate(void)
{
/* Instruct libblockdriver to shut down.
 */

  running = FALSE;
}

/*===========================================================================*
 *				blockdriver_mt_sleep			     *
 *===========================================================================*/
void blockdriver_mt_sleep(void)
{
/* Let the current thread sleep until it gets woken up by the master thread.
 */
  worker_t *wp;

  wp = (worker_t *) mthread_getspecific(worker_key);

  if (wp == NULL)
	panic("blockdriver_mt: master thread cannot sleep");

  mthread_event_wait(&wp->sleep_event);
}

/*===========================================================================*
 *				blockdriver_mt_wakeup			     *
 *===========================================================================*/
void blockdriver_mt_wakeup(thread_id_t id)
{
/* Wake up a sleeping worker thread from the master thread.
 */
  worker_t *wp;
  device_id_t device_id;
  worker_id_t worker_id;

  device_id = TID_DEVICE(id);
  worker_id = TID_WORKER(id);

  assert(device_id >= 0 && device_id < MAX_DEVICES);
  assert(worker_id < MAX_WORKERS);

  wp = &device[device_id].worker[worker_id];

  assert(wp->state == STATE_RUNNING || wp->state == STATE_BUSY);

  mthread_event_fire(&wp->sleep_event);
}

/*===========================================================================*
 *				blockdriver_mt_set_workers		     *
 *===========================================================================*/
void blockdriver_mt_set_workers(device_id_t id, unsigned int workers)
{
/* Set the number of worker threads for the given device.
 */
  device_t *dp;

  assert(id >= 0 && id < MAX_DEVICES);

  if (workers > MAX_WORKERS)
	workers = MAX_WORKERS;

  dp = &device[id];

  /* If we are cleaning up, wake up all threads waiting on a queue event. */
  if (workers == 1 && dp->workers > workers)
	mthread_event_fire_all(&dp->queue_event);

  dp->workers = workers;
}

/*===========================================================================*
 *				blockdriver_mt_is_idle			     *
 *===========================================================================*/
int blockdriver_mt_is_idle(void)
{
/* Return whether the block driver is idle. This means that it has no enqueued
 * requests and no busy worker threads. Used for live update functionality.
 */
  unsigned int did, wid;

  for (did = 0; did < MAX_DEVICES; did++) {
	if (!mq_isempty(did))
		return FALSE;

	for (wid = 0; wid < device[did].workers; wid++)
		if (device[did].worker[wid].state == STATE_BUSY)
			return FALSE;
  }

  return TRUE;
}

/*===========================================================================*
 *				blockdriver_mt_suspend			     *
 *===========================================================================*/
void blockdriver_mt_suspend(void)
{
/* Suspend the driver operation in order to facilitate a live update.
 * Suspension involves shutting down all worker threads, because transferring
 * thread stacks is currently not supported by the state transfer framework.
 */
  unsigned int did;

  assert(running);
  assert(blockdriver_mt_is_idle());

  /* We terminate the worker threads by simulating a driver shutdown. */
  running = FALSE;

  for (did = 0; did < MAX_DEVICES; did++)
	mthread_event_fire_all(&device[did].queue_event);

  master_yield();
}

/*===========================================================================*
 *				blockdriver_mt_resume			     *
 *===========================================================================*/
void blockdriver_mt_resume(void)
{
/* Resume regular operation after a (successful or failed) live update. We do
 * not recreate worker threads; instead, they are recreated lazily as new
 * requests come in.
 */

  assert(!running);

  running = TRUE;
}