docs added

Author: valdmity

pkg/pool/dbpool.go

@@ -39,6 +39,19 @@ var _ DBPool = &InstancePoolImpl{}
 //
 // Returns:
 //   - shard.Shard: The shard that satisfies the callback condition, or nil if no shard satisfies the condition.
+//
+// traverseHostsMatchCB traverses the list of hosts and invokes the provided callback function
+// for each host until the callback returns true. It returns the shard that satisfies the callback
+// condition. If no shard satisfies the condition, it returns nil.
+//
+// Parameters:
+//   - clid: The client ID.
+//   - key: The shard key.
+//   - hosts: The list of hosts to traverse.
+//   - cb: The callback function that takes a shard and returns a boolean value.
+//
+// Returns:
+//   - shard.Shard: The shard that satisfies the callback condition, or nil if no shard satisfies the condition.
 func (s *InstancePoolImpl) traverseHostsMatchCB(
 	clid uint,
 	key kr.ShardKey, hosts []string, cb func(shard.Shard) bool) shard.Shard {
@@ -79,6 +92,20 @@ func (s *InstancePoolImpl) traverseHostsMatchCB(
 // Returns:
 //   - shard.Shard: The selected read-only shard host.
 //   - error: An error if no suitable shard host is found.
+//
+// SelectReadOnlyShardHost selects a read-only shard host from the given list of hosts based on the provided client ID and shard key.
+// It traverses the hosts and performs checks to ensure the selected shard host is suitable for read-only operations.
+// If a suitable shard host is found, it is returned along with a nil error.
+// If no suitable shard host is found, an error is returned with a message indicating the reason for failure.
+//
+// Parameters:
+//   - clid: The client ID.
+//   - key: The shard key.
+//   - hosts: The list of hosts to traverse.
+//
+// Returns:
+//   - shard.Shard: The selected read-only shard host.
+//   - error: An error if no suitable shard host is found.
 func (s *InstancePoolImpl) SelectReadOnlyShardHost(
 	clid uint,
 	key kr.ShardKey, hosts []string) (shard.Shard, error) {
@@ -116,6 +143,20 @@ func (s *InstancePoolImpl) SelectReadOnlyShardHost(
 // Returns:
 //   - shard.Shard: The selected read-write shard host.
 //   - error: An error if no suitable shard host is found.
+//
+// SelectReadWriteShardHost selects a read-write shard host from the given list of hosts based on the provided client ID and shard key.
+// It traverses the hosts and checks if each shard is available and suitable for read-write operations.
+// If a suitable shard is found, it is returned along with no error.
+// If no suitable shard is found, an error is returned indicating the failure reason.
+//
+// Parameters:
+//   - clid: The client ID.
+//   - key: The shard key.
+//   - hosts: The list of hosts to traverse.
+//
+// Returns:
+//   - shard.Shard: The selected read-write shard host.
+//   - error: An error if no suitable shard host is found.
 func (s *InstancePoolImpl) SelectReadWriteShardHost(
 	clid uint,
 	key kr.ShardKey, hosts []string) (shard.Shard, error) {
@@ -154,6 +195,19 @@ func (s *InstancePoolImpl) SelectReadWriteShardHost(
 // Returns:
 //   - shard.Shard: The acquired shard connection.
 //   - error: An error if the connection cannot be established.
+//
+// Connection acquires a new instance connection for a client to a shard with target session attributes.
+// It selects a shard host based on the target session attributes and returns a shard connection.
+// If no connection can be established, it returns an error.
+//
+// Parameters:
+//   - clid: The client ID.
+//   - key: The shard key.
+//   - targetSessionAttrs: The target session attributes.
+//
+// Returns:
+//   - shard.Shard: The acquired shard connection.
+//   - error: An error if the connection cannot be established.
 func (s *InstancePoolImpl) Connection(
 	clid uint,
 	key kr.ShardKey,
@@ -204,6 +258,15 @@ func (s *InstancePoolImpl) Connection(
 	}
 }
 
+// InitRule initializes the backend rule in the instance pool.
+// It takes a pointer to a BackendRule as a parameter and returns an error.
+//
+// Parameters:
+//   - rule: A pointer to a BackendRule representing the backend rule to be initialized.
+//
+// Returns:
+//   - error: An error if there is an error initializing the backend rule, nil otherwise.
+//
 // InitRule initializes the backend rule in the instance pool.
 // It takes a pointer to a BackendRule as a parameter and returns an error.
 //
@@ -216,17 +279,27 @@ func (s *InstancePoolImpl) InitRule(rule *config.BackendRule) error {
 	return s.pool.InitRule(rule)
 }
 
+// ShardMapping returns the shard mapping of the instance pool.
 // ShardMapping returns the shard mapping of the instance pool.
 func (s *InstancePoolImpl) ShardMapping() map[string]*config.Shard {
 	return s.shardMapping
 }
 
+// List returns a list of shards in the instance pool.
 // List returns a list of shards in the instance pool.
 func (s *InstancePoolImpl) List() []shard.Shard {
 	/* mutex? */
 	return s.pool.List()
 }
 
+// ForEach iterates over each shard in the instance pool and calls the provided callback function.
+// It returns an error if the callback function returns an error.
+//
+// Parameters:
+// - cb: The callback function to be called for each shard in the instance pool.
+//
+// Returns:
+// - error: An error if the callback function returns an error.
 // ForEach iterates over each shard in the instance pool and calls the provided callback function.
 // It returns an error if the callback function returns an error.
 //
@@ -249,6 +322,15 @@ func (s *InstancePoolImpl) ForEach(cb func(sh shard.Shardinfo) error) error {
 //
 // Returns:
 // - error: An error if the shard is discarded or if there is an error putting the shard into the pool.
+// Put puts a shard into the instance pool.
+// It discards the shard if it is not synchronized or if it is not in idle transaction status.
+// Otherwise, it puts the shard into the pool.
+//
+// Parameters:
+// - sh: The shard to be put into the pool.
+//
+// Returns:
+// - error: An error if the shard is discarded or if there is an error putting the shard into the pool.
 func (s *InstancePoolImpl) Put(sh shard.Shard) error {
 	if sh.Sync() != 0 {
 		spqrlog.Zero.Error().
@@ -267,6 +349,14 @@ func (s *InstancePoolImpl) Put(sh shard.Shard) error {
 	return s.pool.Put(sh)
 }
 
+// ForEachPool iterates over each pool in the instance pool and calls the provided callback function.
+// It returns an error if the callback function returns an error.
+//
+// Parameters:
+// - cb: The callback function to be called for each pool in the instance pool.
+//
+// Returns:
+// - error: An error if the callback function returns an error.
 // ForEachPool iterates over each pool in the instance pool and calls the provided callback function.
 // It returns an error if the callback function returns an error.
 //
@@ -279,6 +369,14 @@ func (s *InstancePoolImpl) ForEachPool(cb func(pool Pool) error) error {
 	return s.pool.ForEachPool(cb)
 }
 
+// Cut removes a shard from the instance pool based on the provided host.
+// It returns the removed shard.
+//
+// Parameters:
+// - host: The host of the shard to be removed.
+//
+// Returns:
+// - []shard.Shard: The removed shard.
 // Cut removes a shard from the instance pool based on the provided host.
 // It returns the removed shard.
 //
@@ -291,6 +389,14 @@ func (s *InstancePoolImpl) Cut(host string) []shard.Shard {
 	return s.pool.Cut(host)
 }
 
+// Discard removes a shard from the instance pool.
+// It returns an error if the removal fails.
+//
+// Parameters:
+// - sh: The shard to be removed from the pool.
+//
+// Returns:
+// - error: An error if the removal fails, nil otherwise.
 // Discard removes a shard from the instance pool.
 // It returns an error if the removal fails.
 //
@@ -311,6 +417,7 @@ func (s *InstancePoolImpl) Discard(sh shard.Shard) error {
 // Parameters:
 //   - mapping: A map containing the shard mapping, where the key is the shard name
 //     and the value is a pointer to the corresponding Shard configuration.
+//   - sp: A StartupParams
 //
 // Returns:
 //   - DBPool: A DBPool interface that represents the created pool.