Skip to content

Commit

Permalink
doc: update inline comments
Browse files Browse the repository at this point in the history 
- replace "tarantool" with "Tarantool"
- replace "lua" with "Lua"
- remove apostrophes in comments
- fixed typos
- remove unneeded empty lines that break documentation generation
- add a version where new methods or packages were added
- remove apostrophes in comment for Connection
- add dots to the end of sentences
- start sentences with capitalized letter

Part of #123
  • Loading branch information
@ligurio
ligurio committed Apr 14, 2022
1 parent 0c89df2 commit 717061a
Show file tree
Hide file tree
Showing 10 changed files with 161 additions and 129 deletions.
12 changes: 6 additions & 6 deletions client_tools.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import (
"gopkg.in/vmihailenco/msgpack.v2"
)

// IntKey is utility type for passing integer key to Select*, Update* and Delete*
// IntKey is utility type for passing integer key to Select*, Update* and Delete*.
// It serializes to array with single integer element.
type IntKey struct {
I int
Expand All @@ -16,7 +16,7 @@ func (k IntKey) EncodeMsgpack(enc *msgpack.Encoder) error {
return nil
}

// UintKey is utility type for passing unsigned integer key to Select*, Update* and Delete*
// UintKey is utility type for passing unsigned integer key to Select*, Update* and Delete*.
// It serializes to array with single integer element.
type UintKey struct {
I uint
Expand All @@ -28,7 +28,7 @@ func (k UintKey) EncodeMsgpack(enc *msgpack.Encoder) error {
return nil
}

// UintKey is utility type for passing string key to Select*, Update* and Delete*
// UintKey is utility type for passing string key to Select*, Update* and Delete*.
// It serializes to array with single string element.
type StringKey struct {
S string
Expand All @@ -40,8 +40,8 @@ func (k StringKey) EncodeMsgpack(enc *msgpack.Encoder) error {
return nil
}

// IntIntKey is utility type for passing two integer keys to Select*, Update* and Delete*
// It serializes to array with two integer elements
// IntIntKey is utility type for passing two integer keys to Select*, Update* and Delete*.
// It serializes to array with two integer elements.
type IntIntKey struct {
I1, I2 int
}
Expand All @@ -53,7 +53,7 @@ func (k IntIntKey) EncodeMsgpack(enc *msgpack.Encoder) error {
return nil
}

// Op - is update operation
// Op - is update operation.
type Op struct {
Op string
Field int
Expand Down
117 changes: 57 additions & 60 deletions connection.go
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
// Package with implementation of methods and structures for work with
// Tarantool instance.
package tarantool

import (
Expand Down Expand Up @@ -27,26 +29,26 @@ type ConnEventKind int
type ConnLogKind int

const (
// Connect signals that connection is established or reestablished
// Connected signals that connection is established or reestablished.
Connected ConnEventKind = iota + 1
// Disconnect signals that connection is broken
// Disconnected signals that connection is broken.
Disconnected
// ReconnectFailed signals that attempt to reconnect has failed
// ReconnectFailed signals that attempt to reconnect has failed.
ReconnectFailed
// Either reconnect attempts exhausted, or explicit Close is called
// Either reconnect attempts exhausted, or explicit Close is called.
Closed

// LogReconnectFailed is logged when reconnect attempt failed
// LogReconnectFailed is logged when reconnect attempt failed.
LogReconnectFailed ConnLogKind = iota + 1
// LogLastReconnectFailed is logged when last reconnect attempt failed,
// connection will be closed after that.
LogLastReconnectFailed
// LogUnexpectedResultId is logged when response with unknown id were received.
// LogUnexpectedResultId is logged when response with unknown id was received.
// Most probably it is due to request timeout.
LogUnexpectedResultId
)

// ConnEvent is sent throw Notify channel specified in Opts
// ConnEvent is sent throw Notify channel specified in Opts.
type ConnEvent struct {
Conn *Connection
Kind ConnEventKind
Expand Down Expand Up @@ -80,47 +82,47 @@ func (d defaultLogger) Report(event ConnLogKind, conn *Connection, v ...interfac
}
}

// Connection is a handle to Tarantool.
// Connection is a handle with a single connection to a Tarantool instance.
//
// It is created and configured with Connect function, and could not be
// reconfigured later.
//
// It is could be "Connected", "Disconnected", and "Closed".
// Connection could be in three possible states:
//
// When "Connected" it sends queries to Tarantool.
// - In "Connected" state it sends queries to Tarantool.
//
// When "Disconnected" it rejects queries with ClientError{Code: ErrConnectionNotReady}
// - In "Disconnected" state it rejects queries with ClientError{Code:
// ErrConnectionNotReady}
//
// When "Closed" it rejects queries with ClientError{Code: ErrConnectionClosed}
//
// Connection could become "Closed" when Connection.Close() method called,
// or when Tarantool disconnected and Reconnect pause is not specified or
// MaxReconnects is specified and MaxReconnect reconnect attempts already performed.
// - In "Closed" state it rejects queries with ClientError{Code:
// ErrConnectionClosed}. Connection could become "Closed" when
// Connection.Close() method called, or when Tarantool disconnected and
// Reconnect pause is not specified or MaxReconnects is specified and
// MaxReconnect reconnect attempts already performed.
//
// You may perform data manipulation operation by calling its methods:
// Call*, Insert*, Replace*, Update*, Upsert*, Call*, Eval*.
//
// In any method that accepts `space` you my pass either space number or
// space name (in this case it will be looked up in schema). Same is true for `index`.
// In any method that accepts space you my pass either space number or space
// name (in this case it will be looked up in schema). Same is true for index.
//
// ATTENTION: `tuple`, `key`, `ops` and `args` arguments for any method should be
// ATTENTION: tuple, key, ops and args arguments for any method should be
// and array or should serialize to msgpack array.
//
// ATTENTION: `result` argument for *Typed methods should deserialize from
// ATTENTION: result argument for *Typed methods should deserialize from
// msgpack array, cause Tarantool always returns result as an array.
// For all space related methods and Call* (but not Call17*) methods Tarantool
// always returns array of array (array of tuples for space related methods).
// For Eval* and Call17* tarantool always returns array, but does not forces
// For Eval* and Call17* Tarantool always returns array, but does not forces
// array of arrays.

type Connection struct {
addr string
c net.Conn
mutex sync.Mutex
// Schema contains schema loaded on connection.
Schema *Schema
requestId uint32
// Greeting contains first message sent by tarantool
// Greeting contains first message sent by Tarantool.
Greeting *Greeting

shard []connShard
Expand All @@ -134,7 +136,7 @@ type Connection struct {
lenbuf [PacketLengthBytes]byte
}

var _ = Connector(&Connection{}) // check compatibility with connector interface
var _ = Connector(&Connection{}) // Check compatibility with connector interface.

type connShard struct {
rmut sync.Mutex
Expand All @@ -148,7 +150,7 @@ type connShard struct {
_pad [16]uint64
}

// Greeting is a message sent by tarantool on connect.
// Greeting is a message sent by Tarantool on connect.
type Greeting struct {
Version string
auth string
Expand All @@ -157,22 +159,22 @@ type Greeting struct {
// Opts is a way to configure Connection
type Opts struct {
// Timeout is requests timeout.
// Also used to setup net.TCPConn.Set(Read|Write)Deadline
// Also used to setup net.TCPConn.Set(Read|Write)Deadline.
Timeout time.Duration
// Reconnect is a pause between reconnection attempts.
// If specified, then when tarantool is not reachable or disconnected,
// If specified, then when Tarantool is not reachable or disconnected,
// new connect attempt is performed after pause.
// By default, no reconnection attempts are performed,
// so once disconnected, connection becomes Closed.
Reconnect time.Duration
// MaxReconnects is a maximum reconnect attempts.
// After MaxReconnects attempts Connection becomes closed.
MaxReconnects uint
// User name for authorization
// User name for authorization.
User string
// Pass is password for authorization
// Pass is password for authorization.
Pass string
// RateLimit limits number of 'in-fly' request, ie already put into
// RateLimit limits number of 'in-fly' request, i.e. already put into
// requests queue, but not yet answered by server or timeouted.
// It is disabled by default.
// See RLimitAction for possible actions when RateLimit.reached.
Expand All @@ -191,42 +193,37 @@ type Opts struct {
// By default it is runtime.GOMAXPROCS(-1) * 4
Concurrency uint32
// SkipSchema disables schema loading. Without disabling schema loading,
// there is no way to create Connection for currently not accessible tarantool.
// there is no way to create Connection for currently not accessible Tarantool.
SkipSchema bool
// Notify is a channel which receives notifications about Connection status
// changes.
Notify chan<- ConnEvent
// Handle is user specified value, that could be retrivied with Handle() method
// Handle is user specified value, that could be retrivied with
// Handle() method.
Handle interface{}
// Logger is user specified logger used for error messages
// Logger is user specified logger used for error messages.
Logger Logger
}

// Connect creates and configures new Connection
// Connect creates and configures a new Connection.
//
// Address could be specified in following ways:
//
// TCP connections:
// - tcp://192.168.1.1:3013
// - tcp://my.host:3013
// - tcp:192.168.1.1:3013
// - tcp:my.host:3013
// - 192.168.1.1:3013
// - my.host:3013
// Unix socket:
// - unix:///abs/path/tnt.sock
// - unix:path/tnt.sock
// - /abs/path/tnt.sock - first '/' indicates unix socket
// - ./rel/path/tnt.sock - first '.' indicates unix socket
// - unix/:path/tnt.sock - 'unix/' acts as a "host" and "/path..." as a port
// - TCP connections (tcp://192.168.1.1:3013, tcp://my.host:3013,
// tcp:192.168.1.1:3013, tcp:my.host:3013, 192.168.1.1:3013, my.host:3013)
//
// - Unix socket, first '/' or '.' indicates Unix socket
// (unix:///abs/path/tnt.sock, unix:path/tnt.sock, /abs/path/tnt.sock,
// ./rel/path/tnt.sock, unix/:path/tnt.sock)
//
// Note:
// Notes:
//
// - If opts.Reconnect is zero (default), then connection either already connected
// or error is returned.
//
// - If opts.Reconnect is non-zero, then error will be returned only if authorization// fails. But if Tarantool is not reachable, then it will attempt to reconnect later
// and will not end attempts on authorization failures.
// - If opts.Reconnect is non-zero, then error will be returned only if authorization
// fails. But if Tarantool is not reachable, then it will make an attempt to reconnect later
// and will not finish to make attempts on authorization failures.
func Connect(addr string, opts Opts) (conn *Connection, err error) {
conn = &Connection{
addr: addr,
Expand Down Expand Up @@ -272,10 +269,10 @@ func Connect(addr string, opts Opts) (conn *Connection, err error) {
return nil, err
} else if ok && (ter.Code == ErrNoSuchUser ||
ter.Code == ErrPasswordMismatch) {
/* reported auth errors immediatly */
// Reported auth errors immediately.
return nil, err
} else {
// without SkipSchema it is useless
// Without SkipSchema it is useless.
go func(conn *Connection) {
conn.mutex.Lock()
defer conn.mutex.Unlock()
Expand All @@ -292,7 +289,7 @@ func Connect(addr string, opts Opts) (conn *Connection, err error) {
go conn.timeouts()
}

// TODO: reload schema after reconnect
// TODO: reload schema after reconnect.
if !conn.opts.SkipSchema {
if err = conn.loadSchema(); err != nil {
conn.mutex.Lock()
Expand Down Expand Up @@ -324,12 +321,12 @@ func (conn *Connection) Close() error {
return conn.closeConnection(err, true)
}

// Addr is configured address of Tarantool socket
// Addr returns a configured address of Tarantool socket.
func (conn *Connection) Addr() string {
return conn.addr
}

// RemoteAddr is address of Tarantool socket
// RemoteAddr returns an address of Tarantool socket.
func (conn *Connection) RemoteAddr() string {
conn.mutex.Lock()
defer conn.mutex.Unlock()
Expand All @@ -339,7 +336,7 @@ func (conn *Connection) RemoteAddr() string {
return conn.c.RemoteAddr().String()
}

// LocalAddr is address of outgoing socket
// LocalAddr returns an address of outgoing socket.
func (conn *Connection) LocalAddr() string {
conn.mutex.Lock()
defer conn.mutex.Unlock()
Expand All @@ -349,7 +346,7 @@ func (conn *Connection) LocalAddr() string {
return conn.c.LocalAddr().String()
}

// Handle returns user specified handle from Opts
// Handle returns a user-specified handle from Opts.
func (conn *Connection) Handle() interface{} {
return conn.opts.Handle
}
Expand Down Expand Up @@ -416,7 +413,7 @@ func (conn *Connection) dial() (err error) {
}
}

// Only if connected and authenticated
// Only if connected and authenticated.
conn.lockShards()
conn.c = connection
atomic.StoreUint32(&conn.state, connConnected)
Expand Down Expand Up @@ -873,12 +870,12 @@ func (conn *Connection) nextRequestId() (requestId uint32) {
return atomic.AddUint32(&conn.requestId, 1)
}

// ConfiguredTimeout returns timeout from connection config
// ConfiguredTimeout returns a timeout from connection config.
func (conn *Connection) ConfiguredTimeout() time.Duration {
return conn.opts.Timeout
}

// OverrideSchema sets Schema for the connection
// OverrideSchema sets Schema for the connection.
func (conn *Connection) OverrideSchema(s *Schema) {
if s != nil {
conn.mutex.Lock()
Expand Down
22 changes: 14 additions & 8 deletions errors.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,32 +4,38 @@ import (
"fmt"
)

// Error is wrapper around error returned by Tarantool
// Error is wrapper around error returned by Tarantool.
type Error struct {
Code uint32
Msg string
}

// Error converts an Error to a string.
func (tnterr Error) Error() string {
return fmt.Sprintf("%s (0x%x)", tnterr.Msg, tnterr.Code)
}

// ClientError is connection produced by this client,
// ie connection failures or timeouts.
// ClientError is connection error produced by this client,
// i.e. connection failures or timeouts.
type ClientError struct {
Code uint32
Msg string
}

// Error converts a ClientError to a string.
func (clierr ClientError) Error() string {
return fmt.Sprintf("%s (0x%x)", clierr.Msg, clierr.Code)
}

// Temporary returns true if next attempt to perform request may succeeed.
//
// Currently it returns true when:
// - Connection is not connected at the moment,
// - or request is timeouted,
// - or request is aborted due to rate limit.
//
// - Connection is not connected at the moment
//
// - request is timeouted
//
// - request is aborted due to rate limit
func (clierr ClientError) Temporary() bool {
switch clierr.Code {
case ErrConnectionNotReady, ErrTimeouted, ErrRateLimited:
Expand All @@ -39,7 +45,7 @@ func (clierr ClientError) Temporary() bool {
}
}

// Tarantool client error codes
// Tarantool client error codes.
const (
ErrConnectionNotReady = 0x4000 + iota
ErrConnectionClosed = 0x4000 + iota
Expand All @@ -48,7 +54,7 @@ const (
ErrRateLimited = 0x4000 + iota
)

// Tarantool server error codes
// Tarantool server error codes.
const (
ErrUnknown = 0 // Unknown error
ErrIllegalParams = 1 // Illegal parameters, %s
Expand Down
Loading

0 comments on commit 717061a

Please sign in to comment.