transaction

Documentation

Overview

Package transaction provides API interfaces and implementations of atomic transaction for DeGitX. The workflow and research are explained in the white-paper. The brief description of files in this package:

• hook.go - interfaces for API of git reference-transaction hook exposed for RM.
• manager.go - transaction manager (TM) API for resource manager (RM).
• meta.go - transaction metadata types, such as votes, scopes, identifiers.
• paxos.go - Paxos-commit interfaces, such as acceptors and proposers.
• rm.go - resource manager API for hook and TM.

Index

• type Ballot
• type Hook
• type Manager
• type Proposal
  • func (p Proposal) Compare(o Proposal) int
• type Px1A
• type Px1B
• type Px2A
• type Px2B
• type PxAcceptor
• type PxProposer
• type RMProposer
• type Resource
• type Scope
• type Transaction
• type Vote
• type Votes

Types

type Ballot

type Ballot uint16

Ballot number of proposals in Paxos algorithm

type Hook

type Hook interface {
	// Exit transaction hook with success status
	Continue() error
	// Exit transaction hook with error abort status
	Abort() error
}

Hook API of git reference transaction

type Manager

type Manager interface {
	// Begin a transaction, update votes for RMs.
	// RM starts a transaction when it's prepared. RM doesn't
	// know if the transaction was started already, so it always
	// assume it's not started yet and calls begin-transaction of
	// TM. RM includes all known votes about the transaction
	// into this message, so TM has to merge all votes
	// and manage the transaction state correctly. If TM sees that
	// It receives a quorum of `prepared` votes for each RM,
	// it can decide to commit; or if it receives a quorum
	// of `abort` at least for one RM, it can decide to abort.
	Begin(ctx context.Context, txn Transaction, vts Votes) error

	// Finish a transaction. RM notifies about finished transaction.
	// TM counts finished RM to send synchronous response to the client
	// when all RMs are finished. TM already know the state of the transaction,
	// so it needs only a notification hint from RMs without state parameters.
	Finish(ctx context.Context, node *locators.Node) error
}

Manager of the transaction (TM).

type Proposal

type Proposal struct {
	// Ballot number of the proposal
	Ballot
	// Proposer ID, it should be unique number for each
	// proposer participating in the transaction.
	Proposer uint16
}

Proposal for Paxos protocol

func (Proposal) Compare

func (p Proposal) Compare(o Proposal) int

Compare two proposals

type Px1A

type Px1A struct {
	Proposal
}

Px1A - Paxos 1A message sent from proposer to acceptor

type Px1B

type Px1B struct {
	Max, Acc Ballot
	Value    Vote
}

Px1B - Paxos 1B message sent from acceptor to proposer

type Px2A

type Px2A struct {
	Proposal
	// Value to accept
	Value Vote
}

Px2A - Paxos 2A message sent from proposer to acceptor

type Px2B

type Px2B struct {
	Ballot
}

Px2B - Paxos 2B message sent from acceptor to proposer

type PxAcceptor

type PxAcceptor interface {
	// Prepare takes Paxos 1A message. The proposer chooses ballot number
	// that it believes to be larger than any ballot number for which
	// phase 1 has been performed, and sends it to every acceptor for prepare.
	Prepare(ctx context.Context, msg Px1A) error

	// Accept takes Paxos 2A message. The proposer uses ballot number it has
	// already prepared and acceptor promised to reject all proposals fewer than
	// prepared one. It tries to accept a vote by proposal. If the bigger ballot
	// number was prepared by acceptor between these two operations, acceptor may
	// respond with reject.
	Accept(ctx context.Context, msg Px2A) error
}

PxAcceptor - Paxos acceptor API for proposer

type PxProposer

type PxProposer interface {
	// Promise is a 1B message from acceptor.
	// was prepared succesffully, it includes a proposal ballot
	// number. Promise means that acceptor promises to proposer
	// to reject all next messages if ballot number of such message
	// are less than ballot number of promise.
	Promise(ctx context.Context, msg Px1B) error

	// Accepted message is sent by acceptor as a 2B message, if it
	// successfully accepted 2A message from a proposer.
	Accepted(ctx context.Context, msg Px1B) error

	// Reject is a optimization of Paxos. Instead of ignoring 1A message with
	// small ballot numbers (less than ballot number that acceptor perofrmed any action),
	// acceptor may send a reject message to avoid proposer restarts by timeout and
	// sends a hint with ballot number to help choosing proposer next ballot number
	// greater than any received: bal=max([]rejects)+1
	Reject(ctx context.Context, bal Ballot) error
}

PxProposer - Paxos proposer API for acceptor

type RMProposer

type RMProposer interface {
	// Propose a vote
	Propose(ctx context.Context, v Vote) error
}

RMProposer - proposer API for resource manager

type Resource

type Resource interface {
	// Commit the transaction
	Commit(ctx context.Context, txn string) error

	// Abort the transaction
	Abort(ctx context.Context, txn string) error
}

Resource manager API

type Scope

type Scope struct {
	// Acceptors for this transaction
	Acceptors []*locators.Node
	// TM nodes (first is primary)
	TM []locators.Node
}

Scope of the transaction

type Transaction

type Transaction struct {
	ID string
	Scope
}

Transaction metadata

type Vote

type Vote uint8

Vote of RM

const (
	// VotePrepared means that RM was prepared to commit
	VotePrepared Vote = iota
	// VoteAborted means that RM failed to prepare
	VoteAborted
	// VoteUnkown means that RM was not decided yet
	VoteUnkown
)

type Votes

type Votes struct {
	// Table of votes by RM id
	Table map[*locators.Node]Vote
}

Votes of all RMs