Merge pull request #11 from ReshiAdavan/Sentinel-11

Sentinel-11: linearizability comment thru

Author: ReshiAdavan

linearizability/bitset.go

@@ -1,49 +1,57 @@
 package linearizability
 
+// bitset is a type representing a set of bits.
 type bitset []uint64
 
-// data layout:
-// bits 0-63 are in data[0], the next are in data[1], etc.
-
+// newBitset creates a new bitset with a specified number of bits.
 func newBitset(bits uint) bitset {
 	extra := uint(0)
+	// Determine if an extra chunk is needed for the remaining bits.
 	if bits%64 != 0 {
 		extra = 1
 	}
+	// Calculate total number of 64-bit chunks needed.
 	chunks := bits/64 + extra
 	return bitset(make([]uint64, chunks))
 }
 
+// clone creates a copy of the bitset.
 func (b bitset) clone() bitset {
 	dataCopy := make([]uint64, len(b))
 	copy(dataCopy, b)
 	return bitset(dataCopy)
 }
 
+// bitsetIndex calculates the index of the 64-bit chunk and the bit position within that chunk.
 func bitsetIndex(pos uint) (uint, uint) {
 	return pos / 64, pos % 64
 }
 
+// set sets the bit at the specified position to 1.
 func (b bitset) set(pos uint) bitset {
 	major, minor := bitsetIndex(pos)
 	b[major] |= (1 << minor)
 	return b
 }
 
+// clear sets the bit at the specified position to 0.
 func (b bitset) clear(pos uint) bitset {
 	major, minor := bitsetIndex(pos)
 	b[major] &^= (1 << minor)
 	return b
 }
 
+// get returns true if the bit at the specified position is 1.
 func (b bitset) get(pos uint) bool {
 	major, minor := bitsetIndex(pos)
 	return b[major]&(1<<minor) != 0
 }
 
+// popcnt returns the total number of bits set to 1 in the bitset.
 func (b bitset) popcnt() uint {
 	total := uint(0)
 	for _, v := range b {
+		// Hamming weight algorithm to count set bits efficiently.
 		v = (v & 0x5555555555555555) + ((v & 0xAAAAAAAAAAAAAAAA) >> 1)
 		v = (v & 0x3333333333333333) + ((v & 0xCCCCCCCCCCCCCCCC) >> 2)
 		v = (v & 0x0F0F0F0F0F0F0F0F) + ((v & 0xF0F0F0F0F0F0F0F0) >> 4)
@@ -53,6 +61,7 @@ func (b bitset) popcnt() uint {
 	return total
 }
 
+// hash computes a hash value for the bitset, useful in hash-based collections.
 func (b bitset) hash() uint64 {
 	hash := uint64(b.popcnt())
 	for _, v := range b {
@@ -61,6 +70,7 @@ func (b bitset) hash() uint64 {
 	return hash
 }
 
+// equals checks if two bitsets are equal.
 func (b bitset) equals(b2 bitset) bool {
 	if len(b) != len(b2) {
 		return false

linearizability/linearizability.go

@@ -6,56 +6,53 @@ import (
 	"time"
 )
 
+// Define the type for specifying the kind of entry in history.
 type entryKind bool
 
+// Constants for differentiating call and return entries.
 const (
 	callEntry   entryKind = false
 	returnEntry           = true
 )
 
+// entry represents a single operation (call or return) in the history.
 type entry struct {
 	kind  entryKind
-	value interface{}
-	id    uint
-	time  int64
+	value interface{} // Value associated with the operation.
+	id    uint        // Unique identifier for the operation.
+	time  int64       // Timestamp of the operation.
 }
 
+// byTime implements sort.Interface for sorting entries by their timestamp.
 type byTime []entry
 
-func (a byTime) Len() int {
-	return len(a)
-}
-
-func (a byTime) Swap(i, j int) {
-	a[i], a[j] = a[j], a[i]
-}
-
-func (a byTime) Less(i, j int) bool {
-	return a[i].time < a[j].time
-}
+func (a byTime) Len() int           { return len(a) }
+func (a byTime) Swap(i, j int)      { a[i], a[j] = a[j], a[i] }
+func (a byTime) Less(i, j int) bool { return a[i].time < a[j].time }
 
+// makeEntries converts a slice of Operations to a slice of entries, sorted by time.
 func makeEntries(history []Operation) []entry {
-	var entries []entry = nil
+	var entries []entry
 	id := uint(0)
 	for _, elem := range history {
-		entries = append(entries, entry{
-			callEntry, elem.Input, id, elem.Call})
-		entries = append(entries, entry{
-			returnEntry, elem.Output, id, elem.Return})
+		entries = append(entries, entry{callEntry, elem.Input, id, elem.Call})
+		entries = append(entries, entry{returnEntry, elem.Output, id, elem.Return})
 		id++
 	}
 	sort.Sort(byTime(entries))
 	return entries
 }
 
+// node represents a node in a doubly linked list of entries.
 type node struct {
-	value interface{}
-	match *node // call if match is nil, otherwise return
-	id    uint
-	next  *node
-	prev  *node
+	value interface{} // Value associated with the node.
+	match *node       // Corresponding call/return node. For call entries, match is nil.
+	id    uint        // Unique identifier for the operation.
+	next  *node       // Next node in the list.
+	prev  *node       // Previous node in the list.
 }
 
+// insertBefore inserts a new node before the 'mark' node in the list.
 func insertBefore(n *node, mark *node) *node {
 	if mark != nil {
 		beforeMark := mark.prev
@@ -69,6 +66,7 @@ func insertBefore(n *node, mark *node) *node {
 	return n
 }
 
+// length calculates the length of the linked list starting from 'n'.
 func length(n *node) uint {
 	l := uint(0)
 	for n != nil {
@@ -78,9 +76,10 @@ func length(n *node) uint {
 	return l
 }
 
+// renumber reassigns unique identifiers to events in the history.
 func renumber(events []Event) []Event {
 	var e []Event
-	m := make(map[uint]uint) // renumbering
+	m := make(map[uint]uint) // Map for renumbering.
 	id := uint(0)
 	for _, v := range events {
 		if r, ok := m[v.Id]; ok {
@@ -94,6 +93,7 @@ func renumber(events []Event) []Event {
 	return e
 }
 
+// convertEntries converts a slice of Events to a slice of entries.
 func convertEntries(events []Event) []entry {
 	var entries []entry
 	for _, elem := range events {
@@ -106,9 +106,10 @@ func convertEntries(events []Event) []entry {
 	return entries
 }
 
+// makeLinkedEntries creates a doubly linked list of entries from a slice of entries.
 func makeLinkedEntries(entries []entry) *node {
 	var root *node = nil
-	match := make(map[uint]*node)
+	match := make(map[uint]*node) // Map to track corresponding call/return nodes.
 	for i := len(entries) - 1; i >= 0; i-- {
 		elem := entries[i]
 		if elem.kind {
@@ -125,11 +126,13 @@ func makeLinkedEntries(entries []entry) *node {
 	return root
 }
 
+// cacheEntry is used for caching the states encountered during the linearization check.
 type cacheEntry struct {
-	linearized bitset
-	state      interface{}
+	linearized bitset      // Bitset representing the linearized operations.
+	state      interface{} // State of the model after these operations.
 }
 
+// cacheContains checks if a given cache entry is already in the cache.
 func cacheContains(model Model, cache map[uint64][]cacheEntry, entry cacheEntry) bool {
 	for _, elem := range cache[entry.linearized.hash()] {
 		if entry.linearized.equals(elem.linearized) && model.Equal(entry.state, elem.state) {
@@ -139,11 +142,13 @@ func cacheContains(model Model, cache map[uint64][]cacheEntry, entry cacheEntry)
 	return false
 }
 
+// callsEntry represents an entry in the list of ongoing calls.
 type callsEntry struct {
 	entry *node
-	state interface{}
+	state interface{} // Model state after the call.
 }
 
+// lift removes an entry and its match from the linked list.
 func lift(entry *node) {
 	entry.prev.next = entry.next
 	entry.next.prev = entry.prev
@@ -154,6 +159,7 @@ func lift(entry *node) {
 	}
 }
 
+// unlift re-inserts an entry and its match back into the linked list.
 func unlift(entry *node) {
 	match := entry.match
 	match.prev.next = match
@@ -164,6 +170,7 @@ func unlift(entry *node) {
 	entry.next.prev = entry
 }
 
+// checkSingle checks if a single partition of the history is linearizable.
 func checkSingle(model Model, subhistory *node, kill *int32) bool {
 	n := length(subhistory) / 2
 	linearized := newBitset(n)
@@ -213,6 +220,7 @@ func checkSingle(model Model, subhistory *node, kill *int32) bool {
 	return true
 }
 
+// fillDefault fills in default implementations for missing methods in the model.
 func fillDefault(model Model) Model {
 	if model.Partition == nil {
 		model.Partition = NoPartition
@@ -226,14 +234,12 @@ func fillDefault(model Model) Model {
 	return model
 }
 
+// CheckOperations checks if the operations in the history are linearizable.
 func CheckOperations(model Model, history []Operation) bool {
 	return CheckOperationsTimeout(model, history, 0)
 }
 
-/* 
- * Timeout = 0 means no timeout if this operation times out, then a false positive is possible
- */ 
-
+// CheckOperationsTimeout checks if the operations in the history are linearizable with a timeout.
 func CheckOperationsTimeout(model Model, history []Operation, timeout time.Duration) bool {
 	model = fillDefault(model)
 	partitions := model.Partition(history)
@@ -271,14 +277,12 @@ loop:
 	return ok
 }
 
+// CheckEvents checks if the events in the history are linearizable.
 func CheckEvents(model Model, history []Event) bool {
 	return CheckEventsTimeout(model, history, 0)
 }
 
-/* 
- * timeout = 0 means no timeout if this operation times out, then a false positive is possible
- */ 
- 
+// CheckEventsTimeout checks if the events in the history are linearizable with a timeout.
 func CheckEventsTimeout(model Model, history []Event, timeout time.Duration) bool {
 	model = fillDefault(model)
 	partitions := model.PartitionEvent(history)

linearizability/model.go

@@ -1,48 +1,61 @@
 package linearizability
 
+// Operation represents an operation in the history of a linearizability check.
+// It includes both the input to and output from the operation along with their respective timestamps.
 type Operation struct {
-	Input  interface{}
-	Call   int64 // invocation time
-	Output interface{}
-	Return int64 // response time
+	Input  interface{} // Input of the operation.
+	Call   int64       // Invocation time of the operation.
+	Output interface{} // Output of the operation.
+	Return int64       // Response time of the operation.
 }
 
+// EventKind is a type to distinguish between call and return events.
 type EventKind bool
 
+// Constants for differentiating call and return events.
 const (
-	CallEvent   EventKind = false
-	ReturnEvent EventKind = true
+	CallEvent   EventKind = false // Represents a call event.
+	ReturnEvent EventKind = true  // Represents a return event.
 )
 
+// Event represents either a call or a return event in the history.
 type Event struct {
-	Kind  EventKind
-	Value interface{}
-	Id    uint
+	Kind  EventKind  // Kind of the event (CallEvent or ReturnEvent).
+	Value interface{} // Value associated with the event.
+	Id    uint       // Unique identifier for the event.
 }
 
+// Model defines the structure of the system being checked for linearizability.
+// It includes functions for partitioning the history, initializing the system state,
+// stepping through the operations, and comparing system states.
 type Model struct {
-	// Partition functions, such that a history is linearizable if an only
-	// if each partition is linearizable.
+	// Partition functions divide the history into parts, each of which must be linearizable.
 	Partition      func(history []Operation) [][]Operation
 	PartitionEvent func(history []Event) [][]Event
-	// Initial state of the system.
+
+	// Init initializes the system's state.
 	Init func() interface{}
-	// Step function for the system. Returns whether or not the system
-	// could take this step with the given inputs and outputs and also
-	// returns the new state. This should not mutate the existing state.
+
+	// Step function takes a state and an operation's input and output,
+	// and returns whether the operation is valid in the current state and the new state.
+	// It should not mutate the existing state.
 	Step func(state interface{}, input interface{}, output interface{}) (bool, interface{})
-	// Equality on states.
+
+	// Equal function defines equality for states.
 	Equal func(state1, state2 interface{}) bool
 }
 
+// NoPartition is a default partitioning function that treats the entire history as a single partition.
 func NoPartition(history []Operation) [][]Operation {
 	return [][]Operation{history}
 }
 
+// NoPartitionEvent is a default partitioning function for event histories, treating the entire history as a single partition.
 func NoPartitionEvent(history []Event) [][]Event {
 	return [][]Event{history}
 }
 
+// ShallowEqual is a default equality function that checks for basic equality between two states.
 func ShallowEqual(state1, state2 interface{}) bool {
 	return state1 == state2
 }