Repository: matrixorigin/matrixone
Pull request #3834 (2022-07-08 13:15:35)

logservice: added godoc comments for client
**What type of PR is this?**

- [ ] API-change
- [ ] BUG
- [ ] Improvement
- [x] Documentation
- [ ] Feature
- [ ] Test and CI
- [ ] Code Refactoring

**Which issue(s) this PR fixes:**

issue #

**What this PR does / why we need it:**

Added godoc comments for Log Service client. 

**Special notes for your reviewer:**

Not Available

**Additional documentation (e.g. design docs, usage docs, etc.):**

Not Available



Patch:
diff --git a/pkg/logservice/client.go b/pkg/logservice/client.go
index 55e7c9b5c..e4e3b17ba 100644
--- a/pkg/logservice/client.go
+++ b/pkg/logservice/client.go
@@ -25,7 +25,10 @@ import (
 )
 
 var (
-	ErrDeadlineNotSet  = moerr.NewError(moerr.INVALID_INPUT, "deadline not set")
+	// ErrDeadlineNotSet is returned when deadline is not set in the context.
+	ErrDeadlineNotSet = moerr.NewError(moerr.INVALID_INPUT, "deadline not set")
+	// ErrInvalidDeadline is returned when the specified deadline is invalid, e.g.
+	// deadline is in the past.
 	ErrInvalidDeadline = moerr.NewError(moerr.INVALID_INPUT, "invalid deadline")
 	// ErrIncompatibleClient is returned when write requests are made on read-only clients.
 	ErrIncompatibleClient = moerr.NewError(moerr.INVALID_INPUT, "incompatible client")
@@ -36,25 +39,31 @@ const (
 	defaultWriteSocketSize = 64 * 1024
 )
 
-// IsTempError returns a boolean value indicating whether the specified error is a temp
-// error that worth to be retried, e.g. timeouts, temp network issues, operation can be
-// completed as Raft leader is being elected. Non-temp error means the error is caused
-// by program logics rather than some external factors.
+// IsTempError returns a boolean value indicating whether the specified error
+// is a temp error that worth to be retried, e.g. timeouts, temp network
+// issues. Non-temp error caused by program logics rather than some external
+// factors.
 func IsTempError(err error) bool {
 	return isTempError(err)
 }
 
-type LogServiceClientConfig struct {
-	ReadOnly  bool
-	ShardID   uint64
+// ClientConfig is the configuration for log service clients.
+type ClientConfig struct {
+	// ReadOnly indicates whether this is a read-only client.
+	ReadOnly bool
+	// ShardID is the shard ID of the log service shard to be used.
+	ShardID uint64
+	// ReplicaID is the replica ID of the DN that owns the created client.
 	ReplicaID uint64
-	// LogService nodes service addresses
+	// LogService nodes service addresses. This field is provided for testing
+	// purposes only.
 	ServiceAddresses []string
 }
 
+// Client is the Log Service Client interface exposed to the DN.
 type Client interface {
 	Close() error
-	Config() LogServiceClientConfig
+	Config() ClientConfig
 	Append(ctx context.Context, rec pb.LogRecord) (Lsn, error)
 	Read(ctx context.Context, firstIndex Lsn, maxSize uint64) ([]pb.LogRecord, Lsn, error)
 	Truncate(ctx context.Context, index Lsn) error
@@ -62,7 +71,7 @@ type Client interface {
 }
 
 type client struct {
-	cfg    LogServiceClientConfig
+	cfg    ClientConfig
 	client morpc.RPCClient
 	addr   string
 	req    *RPCRequest
@@ -71,8 +80,12 @@ type client struct {
 
 var _ Client = (*client)(nil)
 
+// CreateClient creates a Log Service client. Each returned client can be used
+// to synchronously issue requests to the Log Service. To send multiple requests
+// to the Log Service in parallel, multiple clients should be created and used
+// to do so.
 func CreateClient(ctx context.Context,
-	name string, cfg LogServiceClientConfig) (Client, error) {
+	cfg ClientConfig) (Client, error) {
 	pool := &sync.Pool{}
 	pool.New = func() interface{} {
 		return &RPCResponse{pool: pool}
@@ -108,14 +121,19 @@ func CreateClient(ctx context.Context,
 	return nil, e
 }
 
+// Close closes the client.
 func (c *client) Close() error {
 	return c.client.Close()
 }
 
-func (c *client) Config() LogServiceClientConfig {
+// Config returns the specified configuration when creating the client.
+func (c *client) Config() ClientConfig {
 	return c.cfg
 }
 
+// Append appends the specified LogRecrd into the Log Service. On success, the
+// assigned Lsn will be returned. For the specified LogRecord, only its Dsta
+// field is used with all other fields ignored by Append().
 func (c *client) Append(ctx context.Context, rec pb.LogRecord) (Lsn, error) {
 	if c.readOnly() {
 		return 0, ErrIncompatibleClient
@@ -124,11 +142,19 @@ func (c *client) Append(ctx context.Context, rec pb.LogRecord) (Lsn, error) {
 	return c.append(ctx, rec)
 }
 
+// Read reads the Log Service from the specified Lsn position until the
+// returned LogRecord set reachs the specified maxSize in bytes. The returned
+// Lsn indicates the next Lsn to use to resume the read, or it means
+// everything available has been read when it equals to the specified Lsn.
 func (c *client) Read(ctx context.Context,
 	firstIndex Lsn, maxSize uint64) ([]pb.LogRecord, Lsn, error) {
 	return c.read(ctx, firstIndex, maxSize)
 }
 
+// Truncate truncates the Log Service log at the specified Lsn with Lsn
+// itself included. This allows the Log Service to free up storage capacities
+// for future appends, all future reads must start after the specified Lsn
+// position.
 func (c *client) Truncate(ctx context.Context, lsn Lsn) error {
 	if c.readOnly() {
 		return ErrIncompatibleClient
@@ -136,6 +162,8 @@ func (c *client) Truncate(ctx context.Context, lsn Lsn) error {
 	return c.truncate(ctx, lsn)
 }
 
+// GetTruncatedIndex returns the largest Lsn value that has been specified for
+// truncation.
 func (c *client) GetTruncatedIndex(ctx context.Context) (Lsn, error) {
 	return c.getTruncatedIndex(ctx)
 }


Test patch:
diff --git a/pkg/logservice/client_test.go b/pkg/logservice/client_test.go
index 0b8158a49..17444e2a6 100644
--- a/pkg/logservice/client_test.go
+++ b/pkg/logservice/client_test.go
@@ -30,7 +30,7 @@ import (
 )
 
 func runClientTest(t *testing.T,
-	readOnly bool, fn func(*testing.T, LogServiceClientConfig, Client)) {
+	readOnly bool, fn func(*testing.T, ClientConfig, Client)) {
 	defer leaktest.AfterTest(t)()
 	cfg := getServiceTestConfig()
 	defer vfs.ReportLeakedFD(cfg.FS, t)
@@ -44,7 +44,7 @@ func runClientTest(t *testing.T,
 	init[2] = service.ID()
 	assert.NoError(t, service.store.StartReplica(1, 2, init, false))
 
-	scfg := LogServiceClientConfig{
+	scfg := ClientConfig{
 		ReadOnly:         readOnly,
 		ShardID:          1,
 		ReplicaID:        2,
@@ -53,7 +53,7 @@ func runClientTest(t *testing.T,
 
 	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
 	defer cancel()
-	c, err := CreateClient(ctx, "shard1", scfg)
+	c, err := CreateClient(ctx, scfg)
 	require.NoError(t, err)
 	defer func() {
 		assert.NoError(t, c.Close())
@@ -63,14 +63,14 @@ func runClientTest(t *testing.T,
 }
 
 func TestClientCanBeCreated(t *testing.T) {
-	fn := func(t *testing.T, cfg LogServiceClientConfig, c Client) {
+	fn := func(t *testing.T, cfg ClientConfig, c Client) {
 	}
 	runClientTest(t, false, fn)
 	runClientTest(t, true, fn)
 }
 
 func TestClientAppend(t *testing.T) {
-	fn := func(t *testing.T, cfg LogServiceClientConfig, c Client) {
+	fn := func(t *testing.T, cfg ClientConfig, c Client) {
 		cmd := make([]byte, 16+headerSize+8)
 		cmd = getAppendCmd(cmd, cfg.ReplicaID)
 		rand.Read(cmd[headerSize+8:])
@@ -92,7 +92,7 @@ func TestClientAppend(t *testing.T) {
 }
 
 func TestClientAppendAlloc(t *testing.T) {
-	fn := func(t *testing.T, cfg LogServiceClientConfig, c Client) {
+	fn := func(t *testing.T, cfg ClientConfig, c Client) {
 		cmd := make([]byte, 16+headerSize+8)
 		cmd = getAppendCmd(cmd, cfg.ReplicaID)
 		rand.Read(cmd[headerSize+8:])
@@ -108,7 +108,7 @@ func TestClientAppendAlloc(t *testing.T) {
 }
 
 func TestClientRead(t *testing.T) {
-	fn := func(t *testing.T, cfg LogServiceClientConfig, c Client) {
+	fn := func(t *testing.T, cfg ClientConfig, c Client) {
 		cmd := make([]byte, 16+headerSize+8)
 		cmd = getAppendCmd(cmd, cfg.ReplicaID)
 		rand.Read(cmd[headerSize+8:])
@@ -140,7 +140,7 @@ func TestClientRead(t *testing.T) {
 }
 
 func TestClientTruncate(t *testing.T) {
-	fn := func(t *testing.T, cfg LogServiceClientConfig, c Client) {
+	fn := func(t *testing.T, cfg ClientConfig, c Client) {
 		cmd := make([]byte, 16+headerSize+8)
 		cmd = getAppendCmd(cmd, cfg.ReplicaID)
 		rand.Read(cmd[headerSize+8:])
@@ -161,7 +161,7 @@ func TestClientTruncate(t *testing.T) {
 }
 
 func TestReadOnlyClientRejectWriteRequests(t *testing.T) {
-	fn := func(t *testing.T, cfg LogServiceClientConfig, c Client) {
+	fn := func(t *testing.T, cfg ClientConfig, c Client) {
 		cmd := make([]byte, 16+headerSize+8)
 		cmd = getAppendCmd(cmd, cfg.ReplicaID)
 		rand.Read(cmd[headerSize+8:])