Skip to content

Commit 869a6cd

Browse files
valdmityvaldmity
committed
docs
1 parent efe1eb8 commit 869a6cd

28 files changed

+1017
-18
lines changed

‎pkg/models/datashards/datashard.go

+25
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,45 @@ type DataShard struct {
1010
Cfg *config.Shard
1111
}
1212

13+
// NewDataShard creates a new DataShard instance with the given name and configuration.
14+
//
15+
// Parameters:
16+
// - name: The name of the shard.
17+
// - cfg: The configuration of the shard.
18+
//
19+
// Returns:
20+
// - *DataShard: The created DataShard instance.
1321
func NewDataShard(name string, cfg *config.Shard) *DataShard {
1422
return &DataShard{
1523
ID: name,
1624
Cfg: cfg,
1725
}
1826
}
1927

28+
// DataShardToProto converts a DataShard object to a proto.Shard object.
29+
// It takes a pointer to a DataShard as input and returns a pointer to a proto.Shard.
30+
//
31+
// Parameters:
32+
// - shard: The DataShard object to convert.
33+
//
34+
// Returns:
35+
// - *proto.Shard: The converted proto.Shard object.
2036
func DataShardToProto(shard *DataShard) *proto.Shard {
2137
return &proto.Shard{
2238
Hosts: shard.Cfg.Hosts,
2339
Id: shard.ID,
2440
}
2541
}
2642

43+
// DataShardFromProto creates a new DataShard instance from the given proto.Shard.
44+
// It initializes the DataShard with the shard ID and hosts from the proto.Shard,
45+
// and sets the shard type to config.DataShard.
46+
//
47+
// Parameters:
48+
// - shard: The proto.Shard object to convert.
49+
//
50+
// Returns:
51+
// - *DataShard: The created DataShard instance.
2752
func DataShardFromProto(shard *proto.Shard) *DataShard {
2853
return NewDataShard(shard.Id, &config.Shard{
2954
Hosts: shard.Hosts,

‎pkg/models/distributions/distribution.go

+77
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,13 @@ type DistributedRelation struct {
1616
DistributionKey []DistributionKeyEntry
1717
}
1818

19+
// DistributedRelationFromDB creates a DistributedRelation object from a qdb.DistributedRelation object.
20+
//
21+
// Parameters:
22+
// - rel: The qdb.DistributedRelation object to convert.
23+
//
24+
// Returns:
25+
// - *DistributedRelation: The created DistributedRelation object.
1926
func DistributedRelationFromDB(rel *qdb.DistributedRelation) *DistributedRelation {
2027
rdistr := &DistributedRelation{
2128
Name: rel.Name,
@@ -31,6 +38,14 @@ func DistributedRelationFromDB(rel *qdb.DistributedRelation) *DistributedRelatio
3138
return rdistr
3239
}
3340

41+
// DistributedRelationToDB converts a DistributedRelation object to a qdb.DistributedRelation object.
42+
// It copies the name and distribution key from the input object to the output object.
43+
//
44+
// Parameters:
45+
// - rel: The DistributedRelation object to convert.
46+
//
47+
// Returns:
48+
// - *qdb.DistributedRelation: The converted qdb.DistributedRelation object.
3449
func DistributedRelationToDB(rel *DistributedRelation) *qdb.DistributedRelation {
3550
rdistr := &qdb.DistributedRelation{
3651
Name: rel.Name,
@@ -46,6 +61,14 @@ func DistributedRelationToDB(rel *DistributedRelation) *qdb.DistributedRelation
4661
return rdistr
4762
}
4863

64+
// DistributedRelatitonToProto converts a DistributedRelation object to a proto.DistributedRelation object.
65+
// It takes a pointer to a DistributedRelation object as input and returns a pointer to a proto.DistributedRelation object.
66+
//
67+
// Parameters:
68+
// - rel: The DistributedRelation object to convert.
69+
//
70+
// Returns:
71+
// - *proto.DistributedRelation: The converted proto.DistributedRelation object.
4972
func DistributedRelatitonToProto(rel *DistributedRelation) *proto.DistributedRelation {
5073
rdistr := &proto.DistributedRelation{
5174
Name: rel.Name,
@@ -61,6 +84,13 @@ func DistributedRelatitonToProto(rel *DistributedRelation) *proto.DistributedRel
6184
return rdistr
6285
}
6386

87+
// DistributedRelationFromProto converts a proto.DistributedRelation object to a DistributedRelation object.
88+
//
89+
// Parameters:
90+
// - rel: The proto.DistributedRelation object to convert.
91+
//
92+
// Returns:
93+
// - *DistributedRelation: The created DistributedRelation object.
6494
func DistributedRelationFromProto(rel *proto.DistributedRelation) *DistributedRelation {
6595
rdistr := &DistributedRelation{
6696
Name: rel.Name,
@@ -76,6 +106,13 @@ func DistributedRelationFromProto(rel *proto.DistributedRelation) *DistributedRe
76106
return rdistr
77107
}
78108

109+
// DistributedRelationFromSQL converts a spqrparser.DistributedRelation object to a DistributedRelation object.
110+
//
111+
// Parameters:
112+
// - rel: The spqrparser.DistributedRelation object to convert.
113+
//
114+
// Returns:
115+
// - *DistributedRelation: The created DistributedRelation object.
79116
func DistributedRelationFromSQL(rel *spqrparser.DistributedRelation) *DistributedRelation {
80117
rdistr := &DistributedRelation{
81118
Name: rel.Name,
@@ -100,6 +137,14 @@ type Distribution struct {
100137

101138
// local table sharding distr -> route to world
102139

140+
// NewDistribution creates a new Distribution with the specified ID and column types.
141+
//
142+
// Parameters:
143+
// - id: The ID of the distribution.
144+
// - coltypes: The column types to be used.
145+
//
146+
// Returns:
147+
// - *Distribution: The created Distribution object.
103148
func NewDistribution(id string, coltypes []string) *Distribution {
104149
return &Distribution{
105150
Id: id,
@@ -108,10 +153,20 @@ func NewDistribution(id string, coltypes []string) *Distribution {
108153
}
109154
}
110155

156+
// ID returns the ID of the distribution.
111157
func (s *Distribution) ID() string {
112158
return s.Id
113159
}
114160

161+
// DistributionFromDB creates a new Distribution object from a qdb.Distribution object.
162+
// It initializes the new Distribution with the provided ID and column types, and
163+
// populates its relations by converting the relations from the qdb.Distribution object.
164+
//
165+
// Parameters:
166+
// - distr: The qdb.Distribution object to convert.
167+
//
168+
// Returns:
169+
// - *Distribution: The created Distribution object.
115170
func DistributionFromDB(distr *qdb.Distribution) *Distribution {
116171
ret := NewDistribution(distr.ID, distr.ColTypes)
117172
for name, val := range distr.Relations {
@@ -121,6 +176,13 @@ func DistributionFromDB(distr *qdb.Distribution) *Distribution {
121176
return ret
122177
}
123178

179+
// DistributionFromProto creates a Distribution object from a proto.Distribution object.
180+
//
181+
// Parameters:
182+
// - ds: The proto.Distribution object to convert.
183+
//
184+
// Returns:
185+
// - *Distribution: The created Distribution object.
124186
func DistributionFromProto(ds *proto.Distribution) *Distribution {
125187
return &Distribution{
126188
Id: ds.Id,
@@ -135,6 +197,13 @@ func DistributionFromProto(ds *proto.Distribution) *Distribution {
135197
}
136198
}
137199

200+
// DistributionToProto converts a Distribution object to its corresponding proto.Distribution representation.
201+
//
202+
// Parameters:
203+
// - ds: The Distribution object to convert.
204+
//
205+
// Returns:
206+
// - *proto.Distribution: The converted proto.Distribution object.
138207
func DistributionToProto(ds *Distribution) *proto.Distribution {
139208
drels := make([]*proto.DistributedRelation, 0)
140209
for _, r := range ds.Relations {
@@ -147,6 +216,14 @@ func DistributionToProto(ds *Distribution) *proto.Distribution {
147216
}
148217
}
149218

219+
// DistributionToDB converts a Distribution struct to a qdb.Distribution struct.
220+
// It takes a pointer to a Distribution struct (ds) as input and returns a pointer to a qdb.Distribution struct.
221+
//
222+
// Parameters:
223+
// - ds: The Distribution struct to convert.
224+
//
225+
// Returns:
226+
// - *qdb.Distribution: The converted qdb.Distribution struct.
150227
func DistributionToDB(ds *Distribution) *qdb.Distribution {
151228
d := &qdb.Distribution{
152229
ID: ds.Id,

‎pkg/models/hashfunction/hashfunction.go

+30
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,16 @@ var (
2121
errNoSuchHashFunction = fmt.Errorf("no such hash function")
2222
)
2323

24+
// ApplyHashFunction applies the specified hash function to the input byte slice.
25+
// It returns the hashed byte slice and an error, if any.
26+
//
27+
// Parameters:
28+
// - inp: The input byte slice to hash.
29+
// - hf: The hash function to apply.
30+
//
31+
// Returns:
32+
// - []byte: The hashed byte slice.
33+
// - error: An error if any error occurs during the process.
2434
func ApplyHashFunction(inp []byte, hf HashFunctionType) ([]byte, error) {
2535
switch hf {
2636
case HashFunctionIdent:
@@ -36,6 +46,16 @@ func ApplyHashFunction(inp []byte, hf HashFunctionType) ([]byte, error) {
3646
}
3747
}
3848

49+
// HashFunctionByName returns the corresponding HashFunctionType based on the given hash function name.
50+
// It accepts a string parameter `hfn` representing the hash function name.
51+
// It returns the corresponding HashFunctionType and an error if the hash function name is not recognized.
52+
//
53+
// Parameters:
54+
// - hfn: The name of the hash function.
55+
//
56+
// Returns:
57+
// - HashFunctionType: The corresponding HashFunctionType.
58+
// - error: An error if the hash function name is not recognized.
3959
func HashFunctionByName(hfn string) (HashFunctionType, error) {
4060
switch hfn {
4161
case "identity", "ident", "":
@@ -48,6 +68,16 @@ func HashFunctionByName(hfn string) (HashFunctionType, error) {
4868
return 0, errNoSuchHashFunction
4969
}
5070
}
71+
72+
// ToString converts a HashFunctionType to its corresponding string representation.
73+
// It takes a HashFunctionType as input and returns the string representation of the hash function.
74+
// If the input HashFunctionType is not recognized, an empty string is returned.
75+
//
76+
// Parameters:
77+
// - hf: The HashFunctionType to convert.
78+
//
79+
// Returns:
80+
// - string: The string representation of the hash function.
5181
func ToString(hf HashFunctionType) string {
5282
switch hf {
5383
case HashFunctionIdent:

‎pkg/models/kr/keyrange.go

+29-1
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@ package kr
22

33
import (
44
"fmt"
5+
"strings"
6+
57
"github.com/pg-sharding/spqr/pkg/models/distributions"
68
proto "github.com/pg-sharding/spqr/pkg/protos"
79
"github.com/pg-sharding/spqr/qdb"
810
spqrparser "github.com/pg-sharding/spqr/yacc/console"
9-
"strings"
1011
)
1112

1213
type KeyRangeBound []byte
@@ -24,6 +25,8 @@ type KeyRange struct {
2425
}
2526

2627
// TODO : unit tests
28+
// CmpRangesLess compares two byte slices, kr and other, and returns true if kr is less than other.
29+
// The comparison is based on the length of the slices and the lexicographic order of their string representations.
2730
func CmpRangesLess(kr []byte, other []byte) bool {
2831
if len(kr) == len(other) {
2932
return string(kr) < string(other)
@@ -33,6 +36,9 @@ func CmpRangesLess(kr []byte, other []byte) bool {
3336
}
3437

3538
// TODO : unit tests
39+
// CmpRangesLessEqual compares two byte slices, kr and other, and returns true if kr is less than or equal to other.
40+
// The comparison is done by comparing the lengths of the slices first. If the lengths are equal, the function compares the byte values lexicographically.
41+
// Returns true if kr is less than or equal to other, false otherwise.
3642
func CmpRangesLessEqual(kr []byte, other []byte) bool {
3743
if len(kr) == len(other) {
3844
return string(kr) <= string(other)
@@ -42,6 +48,8 @@ func CmpRangesLessEqual(kr []byte, other []byte) bool {
4248
}
4349

4450
// TODO : unit tests
51+
// CmpRangesEqual compares two byte slices, kr and other, and returns true if they are equal.
52+
// It checks if the lengths of kr and other are the same, and then compares their string representations.
4553
func CmpRangesEqual(kr []byte, other []byte) bool {
4654
if len(kr) == len(other) {
4755
return string(kr) == string(other)
@@ -51,6 +59,8 @@ func CmpRangesEqual(kr []byte, other []byte) bool {
5159
}
5260

5361
// TODO : unit tests
62+
// KeyRangeFromDB converts a qdb.KeyRange object to a KeyRange object.
63+
// It creates a new KeyRange object with the values from the qdb.KeyRange object.
5464
func KeyRangeFromDB(kr *qdb.KeyRange) *KeyRange {
5565
return &KeyRange{
5666
LowerBound: kr.LowerBound,
@@ -61,6 +71,9 @@ func KeyRangeFromDB(kr *qdb.KeyRange) *KeyRange {
6171
}
6272

6373
// TODO : unit tests
74+
// KeyRangeFromSQL converts a spqrparser.KeyRangeDefinition into a KeyRange.
75+
// If kr is nil, it returns nil.
76+
// Otherwise, it creates a new KeyRange with the provided values and returns a pointer to it.
6477
func KeyRangeFromSQL(kr *spqrparser.KeyRangeDefinition) *KeyRange {
6578
if kr == nil {
6679
return nil
@@ -74,6 +87,8 @@ func KeyRangeFromSQL(kr *spqrparser.KeyRangeDefinition) *KeyRange {
7487
}
7588

7689
// TODO : unit tests
90+
// KeyRangeFromProto converts a protobuf KeyRangeInfo to a KeyRange object.
91+
// If the input KeyRangeInfo is nil, it returns nil.
7792
func KeyRangeFromProto(kr *proto.KeyRangeInfo) *KeyRange {
7893
if kr == nil {
7994
return nil
@@ -87,6 +102,8 @@ func KeyRangeFromProto(kr *proto.KeyRangeInfo) *KeyRange {
87102
}
88103

89104
// TODO : unit tests
105+
// ToDB converts the KeyRange struct to a qdb.KeyRange struct.
106+
// It returns a pointer to the converted qdb.KeyRange struct.
90107
func (kr *KeyRange) ToDB() *qdb.KeyRange {
91108
return &qdb.KeyRange{
92109
LowerBound: kr.LowerBound,
@@ -97,6 +114,7 @@ func (kr *KeyRange) ToDB() *qdb.KeyRange {
97114
}
98115

99116
// TODO : unit tests
117+
// ToProto converts the KeyRange struct to a protobuf KeyRangeInfo message.
100118
func (kr *KeyRange) ToProto() *proto.KeyRangeInfo {
101119
return &proto.KeyRangeInfo{
102120
KeyRange: &proto.KeyRange{
@@ -110,6 +128,16 @@ func (kr *KeyRange) ToProto() *proto.KeyRangeInfo {
110128

111129
// GetKRCondition returns SQL condition for elements of distributed relation between two key ranges
112130
// TODO support multidimensional key ranges
131+
//
132+
// Parameters:
133+
// - ds: The distribution object.
134+
// - rel: The distributed relation object.
135+
// - kRange: The key range object.
136+
// - upperBound: The upper bound of the key range.
137+
// - prefix: The prefix to use for the column names.
138+
//
139+
// Returns:
140+
// - string: The SQL condition for the key range.
113141
func GetKRCondition(ds *distributions.Distribution, rel *distributions.DistributedRelation, kRange *KeyRange, upperBound KeyRangeBound, prefix string) string {
114142
buf := make([]string, len(rel.DistributionKey))
115143
for i, entry := range rel.DistributionKey {

‎pkg/models/kr/keyrange_test.go

+6-1
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
11
package kr_test
22

33
import (
4+
"testing"
5+
46
"github.com/pg-sharding/spqr/pkg/models/distributions"
57
"github.com/pg-sharding/spqr/pkg/models/kr"
68
"github.com/stretchr/testify/assert"
7-
"testing"
89
)
910

11+
// TestGetKRCondition is a unit test function that tests the behavior of the GetKRCondition function.
12+
// It verifies that the generated condition string matches the expected result for different test cases.
13+
// The test cases include various combinations of distributions, distributed relations, key ranges, upper bounds, and prefixes.
14+
// The function uses the assert package to compare the generated condition with the expected result.
1015
func TestGetKRCondition(t *testing.T) {
1116
assert := assert.New(t)
1217

0 commit comments

Comments
 (0)