System and User Procedures. More...

Detailed Description

System and User Procedures.

This module manages computational tasks (Procedures here after) that can be executed on worker threads.

What is a procedure: In a nutshell, a procedure receives inputs and runs on one worker thread, then outputs the results along with error code/stack if failed. This is the unit of tasks one can give to Thread and Thread-Group module. Input/output are of arbitrary format. FOEDUS simply receives/sends a byte array of up to some size (configuration parameter) as data via shared memory. It's left to the procedure to serialize/deserialize the values. The only constraint is that the data must be self-contained. You can't put pointers in it. If some result must be stored in remotely-accessible manner, you can put them in a storage.

Procedure signature

Every procedure has the following function signature.

ErrorStack procedure(const ProcArguments& args);

context is the thread context of the pre-allocated thread that runs the impersonated session (see Thread-Pool and Impersonation for more details about impersonation).
input_buffer is an arbitrary input data given by the user themselves as of impersonation.
output_buffer is an arbitrary output data that will be returned to the session when the procedure completes.

Granulality of a procedure: Although a procedure in usual databases run just one transaction, a procedure in FOEDUS can run an arbitary number of transactions. A procedure can be the entire user application, too. Think of our procedure as a way to distribute user code to each SOC. Once attached to a worker thread, a procedure can run arbitrary code and it is the intended use. If you attach/detach an individual transaction as one procedure, the inter-process communication will cost a lot.

System and User Procedures: System procedures are a fixed set of procedures provided by FOEDUS itself. Users can invoke them, but they cannot add/modify them. As all system stored procedures are built-in to FOEDUS library, they are automatically avaialble in all SOCs. Names of system stored procedures start with "sys_". User procedures are what user code defines. To register the procedures, the user code has to do one of the followings.

Local-only User Procedures (function pointer)

This is the easiest way to define and execute user procedures. In fact, most test code uses this handy procedure type. The user simply defines a method and registers function pointer. However, this type of procedures can be used only when:

child SOC engines are of foedus::EngineType::kChildEmulated type.
child SOC engines are of foedus::EngineType::kChildForked type and the user pre-registers the function pointer BEFORE the fork (Engine's initialize()).

Individually registered User Procedures

Otherwise, the user has to register the procedures in each SOC because multiple processes do not share address space nor have necessarily same set of shared libraries loaded. We provide a few ways to register procedures in that case.

Shared libraries. Users can specify file/folder of shared libraries to load in each SOC. At the start up of each SOC, we load these shared libraries, which can register procedures.
Overwrite main() and use spawn() type of SOC launching. User can write their main() so that it initializes child SOC engines and then registers function pointers locally.

See also: SOC and IPC; foedus::EngineType

Collaboration diagram for System and User Procedures:

Files
file	fwd.hpp
	Forward declarations of classes in proc package.

file	proc_id.hpp
	Typedefs of ID types used in procedure package.

Classes
struct	foedus::proc::ProcArguments
	Set of arguments, both inputs and outputs, given to each procedure. More...

class	foedus::proc::ProcManager
	Procedure manager, which maintains the list of system/user procedures. More...

struct	foedus::proc::ProcManagerPimpl::SharedData
	All shared data in this module. More...

class	foedus::proc::ProcManagerPimpl
	Pimpl object of ProcManager. More...

struct	foedus::proc::ProcOptions
	Set of options for loading system/user procedures. More...

Typedefs
typedef assorted::FixedString< 60 >	foedus::proc::ProcName
	Represents a unique name of a procedure. More...

typedef uint32_t	foedus::proc::LocalProcId
	Represents a locally-unique ID of a procedure in one SOC. More...

typedef uint64_t	foedus::proc::GlobalProcId
	A globally unique ID of a procedure. More...

typedef ErrorStack(*	foedus::proc::Proc) (const ProcArguments &args)
	A function pointer of a user/system stored procedure. More...

typedef std::pair< ProcName, Proc >	foedus::proc::ProcAndName
	Just a std::pair<ProcName, Proc>. More...

Class Documentation

struct foedus::proc::ProcArguments

Set of arguments, both inputs and outputs, given to each procedure.

Definition at line 81 of file proc_id.hpp.

Collaboration diagram for foedus::proc::ProcArguments:

[legend]

Class Members
Thread *	context_	[IN] Thread on which the procedure is running
Engine *	engine_	[IN] Database Engine
const void *	input_buffer_	[IN] Arbitrary user input given to the procedure
uint32_t	input_len_	[IN] Byte length of input_buffer_
void *	output_buffer_	[OUT] Arbitrary user output buffer given to the procedure
uint32_t	output_buffer_size_	[IN] Byte length of output_buffer_ capacity
uint32_t *	output_used_	[OUT] Byte length of output_buffer_ actually written

Typedef Documentation

typedef uint64_t foedus::proc::GlobalProcId

A globally unique ID of a procedure.

The high 32 bit is the SOC ID, low 32 bit is LocalProcId.

Definition at line 65 of file proc_id.hpp.

typedef uint32_t foedus::proc::LocalProcId

Represents a locally-unique ID of a procedure in one SOC.

The same procedure might have different ID in another SOC. If the procedure is a system procedure, it always has the same ID in all SOCs because system procedures are registered at the beginning. User procedures have larger IDs than all system procedures. 2^32-1 means an invalid procedure.

Definition at line 56 of file proc_id.hpp.

typedef ErrorStack(* foedus::proc::Proc) (const ProcArguments &args)

A function pointer of a user/system stored procedure.

For example, define your procedure as follows:

ErrorStack my_proc(const ProcArguments& args) {
  ...
  return kRetOk;
}
Proc the_proc = &my_proc;
register the_proc and execute it...

Definition at line 113 of file proc_id.hpp.

typedef std::pair<ProcName, Proc> foedus::proc::ProcAndName

Just a std::pair<ProcName, Proc>.

Definition at line 119 of file proc_id.hpp.

typedef assorted::FixedString<60> foedus::proc::ProcName

Represents a unique name of a procedure.

Upto 60 characters so far. It should be a globally unique name, but we do not bother checking it to avoid scalability issue. Usually, all SOCs have the same set of procedures, so it's globally unique, too.

Definition at line 44 of file proc_id.hpp.

Detailed Description

Files

Classes

Typedefs

Class Documentation

Typedef Documentation