foedus::thread::ImpersonateSession Struct Reference

A user session running on an impersonated thread. More...

Detailed Description

A user session running on an impersonated thread.

Overview

This object represents an impersonated session, which is obtained by calling ThreadPool::impersonate() and running the given task on a pre-allocated thread. This object also works as a future to synchronously or asynchronously wait for the completion of the functor from the client program's thread.

Result of Impersonation

The client program has to first check is_valid() for the given session because there are two possible cases as the result of impersonation.

• Impersonation succeded (is_valid()==true), running the task on the impersonated thread. In this case, the client's thread (original thread that invoked ThreadPool::impersonate()) can either wait for the end of the impersonated thread (call wait() or wait_for()), or do other things (e.g., launch more impersonated threads).

• Impersonation failed (is_valid()==false). This might happen for various reasons; timeout, the engine shuts down while waiting, unexpected errors, etc. In this case, get_invalid_cause() indicates the causes of the failed impersonation.

Wait for the completion of the session

When is_valid()==true, this object also behaves as std::shared_future<ErrorStack>, and we actually use it. But, because of the C++11 Keywords in Public Headers issue, we wrap it as a usual class. This object is copiable like std::shared_future, not std::future. Actually, this class is based on std::shared_future just to provide copy semantics for non-C++11 clients. Additional overheads shouldn't matter, hopeully.

Copy/Move

This object is not copy-able because the destructor closes the session in shared memory. However, it is moveable, which moves the ownership (available only with C++11 though).

Definition at line 61 of file impersonate_session.hpp.

#include <impersonate_session.hpp>

Collaboration diagram for foedus::thread::ImpersonateSession:

Public Member Functions
	ImpersonateSession ()
	~ImpersonateSession ()
	ImpersonateSession (const ImpersonateSession &other)=delete
ImpersonateSession &	operator= (const ImpersonateSession &other)=delete
	ImpersonateSession (ImpersonateSession &&other)
ImpersonateSession &	operator= (ImpersonateSession &&other)
bool	is_valid () const
	Returns if the impersonation succeeded. More...
bool	is_running () const
	Returns if the task is still running. More...
ErrorStack	get_result ()
	Waits until the completion of the asynchronous session and retrieves the result. More...
uint64_t	get_output_size ()
	Returns the byte size of output. More...
void	get_output (void *output_buffer)
	Copies the output to the given buffer, whose size must be at least get_output_size(). More...
const void *	get_raw_output_buffer ()
	Returns the pointer to the raw output buffer on shared memory. More...
void	wait () const
	Blocks until the completion of the asynchronous session. More...
bool	wait_for (uint64_t timeout_microsec) const
	Blocks until either the asynchronous session completes or the specified time elapses. More...
void	release ()
	Releases all resources and ownerships this session has acquired. More...

Public Attributes
thread::ThreadRef *	thread_
	The impersonated thread. More...
thread::ThreadTicket	ticket_
	The ticket issued as of impersonation. More...

Friends
std::ostream &	operator<< (std::ostream &o, const ImpersonateSession &v)

Constructor & Destructor Documentation

foedus::thread::ImpersonateSession::ImpersonateSession ( )

inline

Definition at line 62 of file impersonate_session.hpp.

: thread_(CXX11_NULLPTR), ticket_(0) {}

foedus::thread::ImpersonateSession::~ImpersonateSession ( )

inline

Definition at line 63 of file impersonate_session.hpp.

References release().

{ release(); }

Here is the call graph for this function:

foedus::thread::ImpersonateSession::ImpersonateSession ( const ImpersonateSession &  other )

delete

foedus::thread::ImpersonateSession::ImpersonateSession

(

ImpersonateSession &&

other

)

Definition at line 30 of file impersonate_session.cpp.

References thread_, and ticket_.

                                                                 {
  ticket_ = other.ticket_;
  thread_ = other.thread_;
  other.ticket_ = 0;
  other.thread_ = nullptr;
}

Member Function Documentation

void foedus::thread::ImpersonateSession::get_output

(

void *

output_buffer

)

Copies the output to the given buffer, whose size must be at least get_output_size().

Definition at line 58 of file impersonate_session.cpp.

References get_output_size(), foedus::thread::ThreadRef::get_task_output_memory(), and thread_.

                                                       {
  std::memcpy(output_buffer, thread_->get_task_output_memory(), get_output_size());
}

Here is the call graph for this function:

uint64_t foedus::thread::ImpersonateSession::get_output_size

(

)

Returns the byte size of output.

Definition at line 65 of file impersonate_session.cpp.

References foedus::thread::ThreadRef::get_control_block(), foedus::thread::ThreadControlBlock::output_len_, and thread_.

Referenced by get_output().

                                             {
  return thread_->get_control_block()->output_len_;
}

Here is the call graph for this function:

Here is the caller graph for this function:

const void * foedus::thread::ImpersonateSession::get_raw_output_buffer

(

)

Returns the pointer to the raw output buffer on shared memory.

Definition at line 61 of file impersonate_session.cpp.

References foedus::thread::ThreadRef::get_task_output_memory(), and thread_.

                                                      {
  return thread_->get_task_output_memory();
}

Here is the call graph for this function:

ErrorStack foedus::thread::ImpersonateSession::get_result

(

)

Waits until the completion of the asynchronous session and retrieves the result.

It effectively calls wait() in order to wait for the result. The behavior is undefined if is_valid()== false.

Precondition

is_valid()==true

Definition at line 46 of file impersonate_session.cpp.

References foedus::thread::ThreadControlBlock::current_ticket_, ERROR_STACK, foedus::thread::ThreadRef::get_control_block(), is_valid(), foedus::kErrorCodeSessionExpired, foedus::thread::kWaitingForClientRelease, foedus::thread::ThreadControlBlock::proc_result_, foedus::thread::ThreadControlBlock::status_, thread_, ticket_, foedus::FixedErrorStack::to_error_stack(), and wait().

Referenced by foedus::thread::ThreadPool::impersonate_on_numa_core_synchronous(), foedus::thread::ThreadPool::impersonate_on_numa_node_synchronous(), and foedus::thread::ThreadPool::impersonate_synchronous().

                                          {
  wait();
  if (is_valid()) {
    ThreadControlBlock* block = thread_->get_control_block();
    if (block->current_ticket_ != ticket_ || block->status_ != kWaitingForClientRelease) {
      return ERROR_STACK(kErrorCodeSessionExpired);
    }
    return block->proc_result_.to_error_stack();
  } else {
    return ERROR_STACK(kErrorCodeSessionExpired);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

bool foedus::thread::ImpersonateSession::is_running

(

)

const

Returns if the task is still running.

Definition at line 105 of file impersonate_session.cpp.

References ASSERT_ND, foedus::thread::ThreadControlBlock::current_ticket_, foedus::thread::ThreadRef::get_control_block(), foedus::thread::kRunningTask, foedus::thread::kWaitingForExecution, foedus::thread::ThreadControlBlock::status_, thread_, and ticket_.

Referenced by wait(), and wait_for().

                                          {
  ASSERT_ND(thread_->get_control_block()->current_ticket_ >= ticket_);
  if (thread_->get_control_block()->current_ticket_ != ticket_) {
    return false;
  }
  return (thread_->get_control_block()->status_ == kWaitingForExecution ||
    thread_->get_control_block()->status_ == kRunningTask);
}

Here is the call graph for this function:

Here is the caller graph for this function:

bool foedus::thread::ImpersonateSession::is_valid ( ) const

inline

Returns if the impersonation succeeded.

Definition at line 78 of file impersonate_session.hpp.

References CXX11_NULLPTR, thread_, and ticket_.

Referenced by get_result(), foedus::thread::operator<<(), release(), foedus::thread::ThreadRef::try_impersonate(), wait(), and wait_for().

{ return thread_ != CXX11_NULLPTR && ticket_ != 0; }

Here is the caller graph for this function:

ImpersonateSession& foedus::thread::ImpersonateSession::operator= ( const ImpersonateSession &  other )

delete

ImpersonateSession & foedus::thread::ImpersonateSession::operator=

(

ImpersonateSession &&

other

)

Definition at line 37 of file impersonate_session.cpp.

References thread_, and ticket_.

                                                                            {
  ticket_ = other.ticket_;
  thread_ = other.thread_;
  other.ticket_ = 0;
  other.thread_ = nullptr;
  return *this;
}

void foedus::thread::ImpersonateSession::release

(

)

Releases all resources and ownerships this session has acquired.

This method is idempotent, you can call it in any state and many times. Actually, this is also called from the destructor. This method might block if the session is still running. We do not allow the user to discard this session without completing the currently running task.

Attention

Once you invoke this method, you can't call get_result(), get_output(), get_output_size() any longer.

Definition at line 114 of file impersonate_session.cpp.

References foedus::thread::ThreadControlBlock::current_ticket_, foedus::thread::ThreadRef::get_control_block(), is_valid(), foedus::thread::kWaitingForClientRelease, foedus::thread::kWaitingForTask, foedus::thread::ThreadControlBlock::status_, thread_, ticket_, and wait().

Referenced by foedus::thread::ThreadRef::try_impersonate(), and ~ImpersonateSession().

                                 {
  if (!is_valid()) {
    return;
  }

  wait();
  ThreadControlBlock* block = thread_->get_control_block();
  if (block->current_ticket_ == ticket_ && block->status_ == kWaitingForClientRelease) {
    block->status_ = kWaitingForTask;
  }

  ticket_ = 0;
  thread_ = nullptr;
}

Here is the call graph for this function:

Here is the caller graph for this function:

void foedus::thread::ImpersonateSession::wait

(

)

const

Blocks until the completion of the asynchronous session.

The behavior is undefined if is_valid()== false. It effectively calls wait_for(-1) in order to unconditionally wait for the result. This is analogous to std::future::wait().

Precondition

is_valid()==true

Definition at line 69 of file impersonate_session.cpp.

References foedus::soc::SharedPolling::acquire_ticket(), foedus::thread::ThreadRef::get_control_block(), is_running(), is_valid(), foedus::thread::ThreadControlBlock::task_complete_cond_, thread_, and foedus::soc::SharedPolling::timedwait().

Referenced by get_result(), and release().

                                    {
  if (!is_valid() || !is_running()) {
    return;
  }
  ThreadControlBlock* block = thread_->get_control_block();
  while (is_running()) {
    uint64_t demand = block->task_complete_cond_.acquire_ticket();
    if (!is_running()) {
      break;
    }
    block->task_complete_cond_.timedwait(demand, 100000ULL);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

bool foedus::thread::ImpersonateSession::wait_for

(

uint64_t

timeout_microsec

)

const

Blocks until either the asynchronous session completes or the specified time elapses.

Parameters

[in]

timeout_microsec

timeout in microsec. 0 means an instant check without waiting.

Returns

True when we observed completion.

The behavior is undefined if is_valid()== false. It effectively calls wait_for(timeout) in order to conditionally wait for the result. This is analogous to std::future::wait_for().

Precondition

is_valid()==true

Definition at line 83 of file impersonate_session.cpp.

References foedus::soc::SharedPolling::acquire_ticket(), foedus::thread::ThreadRef::get_control_block(), is_running(), is_valid(), foedus::thread::ThreadControlBlock::task_complete_cond_, thread_, and foedus::soc::SharedPolling::timedwait().

                                                                 {
  if (!is_valid()) {
    return false;
  } else if (!is_running()) {
    return true;
  } else if (timeout_microsec == 0) {
    // instant check. return immediately
    return false;
  }

  ThreadControlBlock* block = thread_->get_control_block();
  if (is_running()) {
    uint64_t demand = block->task_complete_cond_.acquire_ticket();
    if (!is_running()) {  // in case it completes between is_running above and acquire_ticket
      return true;
    }
    block->task_complete_cond_.timedwait(demand, timeout_microsec);
  }

  return !is_running();
}

Here is the call graph for this function:

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  o, const ImpersonateSession &  v  )

friend

Definition at line 130 of file impersonate_session.cpp.

                                                                   {
  o << "ImpersonateSession: valid=" << v.is_valid();
  if (v.is_valid()) {
    o << ", thread_id=" << v.thread_->get_thread_id();
  }
  return o;
}

Member Data Documentation

thread::ThreadRef* foedus::thread::ImpersonateSession::thread_

The impersonated thread.

If impersonation failed, null.

Definition at line 136 of file impersonate_session.hpp.

Referenced by get_output(), get_output_size(), get_raw_output_buffer(), get_result(), ImpersonateSession(), is_running(), is_valid(), foedus::thread::operator<<(), operator=(), release(), foedus::thread::ThreadRef::try_impersonate(), wait(), and wait_for().

thread::ThreadTicket foedus::thread::ImpersonateSession::ticket_

The ticket issued as of impersonation.

If impersonation failed, 0.

Definition at line 139 of file impersonate_session.hpp.

Referenced by get_result(), ImpersonateSession(), is_running(), is_valid(), operator=(), release(), and foedus::thread::ThreadRef::try_impersonate().

---

The documentation for this struct was generated from the following files:

• /home/shino/foedus_code/foedus-core/include/foedus/thread/impersonate_session.hpp
• /home/shino/foedus_code/foedus-core/src/foedus/thread/impersonate_session.cpp