github.com/ydb-platform/ydb-go-sdk/v3@v3.89.2/topic/topicwriter/topicwriter.go (about)

     1  package topicwriter
     2  
     3  import (
     4  	"context"
     5  
     6  	"github.com/ydb-platform/ydb-go-sdk/v3/internal/topic/topicwriterinternal"
     7  )
     8  
     9  type (
    10  	Message = topicwriterinternal.PublicMessage
    11  )
    12  
    13  var (
    14  	ErrQueueLimitExceed                      = topicwriterinternal.PublicErrQueueIsFull
    15  	ErrMessagesPutToInternalQueueBeforeError = topicwriterinternal.PublicErrMessagesPutToInternalQueueBeforeError
    16  )
    17  
    18  // Writer represent write session to topic
    19  // It handles connection problems, reconnect to server when need and resend buffered messages
    20  type Writer struct {
    21  	inner *topicwriterinternal.WriterReconnector
    22  }
    23  
    24  // PublicInitialInfo is an information about writer after initialize
    25  type PublicInitialInfo struct {
    26  	LastSeqNum int64
    27  }
    28  
    29  // NewWriter create new writer from internal type. Used internally only.
    30  func NewWriter(writer *topicwriterinternal.WriterReconnector) *Writer {
    31  	return &Writer{
    32  		inner: writer,
    33  	}
    34  }
    35  
    36  // Write send messages to topic
    37  // return after save messages into buffer in async mode (default) and after ack from server in sync mode.
    38  // see topicoptions.WithSyncWrite
    39  //
    40  // The method will wait first initial connection even for async mode, that mean first write may be slower.
    41  // especially when connection has problems.
    42  //
    43  // It returns ErrQueueLimitExceed (must be checked by errors.Is)
    44  // if ctx cancelled before messages put to internal buffer or try to add more messages, that can be put to queue.
    45  // If err != nil you can check errors.Is(err, ErrMessagesPutToInternalQueueBeforeError) for check if the messages
    46  // put to buffer before error. It means that it is messages can be delivered to the server.
    47  func (w *Writer) Write(ctx context.Context, messages ...Message) error {
    48  	return w.inner.Write(ctx, messages)
    49  }
    50  
    51  // WaitInit waits until the reader is initialized
    52  // or an error occurs, return PublicInitialInfo and err
    53  func (w *Writer) WaitInit(ctx context.Context) (err error) {
    54  	_, err = w.inner.WaitInit(ctx)
    55  	if err != nil {
    56  		return err
    57  	}
    58  
    59  	return nil
    60  }
    61  
    62  // WaitInitInfo waits until the reader is initialized
    63  // or an error occurs, return PublicInitialInfo and err
    64  func (w *Writer) WaitInitInfo(ctx context.Context) (info PublicInitialInfo, err error) {
    65  	privateInfo, err := w.inner.WaitInit(ctx)
    66  	if err != nil {
    67  		return PublicInitialInfo{}, err
    68  	}
    69  	publicInfo := PublicInitialInfo{LastSeqNum: privateInfo.LastSeqNum}
    70  
    71  	return publicInfo, nil
    72  }
    73  
    74  // Close will flush rested messages from buffer and close the writer.
    75  // You can't write new messages after call Close
    76  func (w *Writer) Close(ctx context.Context) error {
    77  	return w.inner.Close(ctx)
    78  }
    79  
    80  // Flush waits till all in-flight messages are acknowledged.
    81  func (w *Writer) Flush(ctx context.Context) error {
    82  	return w.inner.Flush(ctx)
    83  }
    84  
    85  // TxWriter used for send messages to the transaction
    86  //
    87  // Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental
    88  type TxWriter struct {
    89  	inner *topicwriterinternal.WriterWithTransaction
    90  }
    91  
    92  func NewTxWriterInternal(w *topicwriterinternal.WriterWithTransaction) *TxWriter {
    93  	return &TxWriter{inner: w}
    94  }
    95  
    96  // Write messages to the transaction
    97  //
    98  // It has not retries. If fails - needs to retry full transaction, as with any other
    99  // error with table.
   100  //
   101  // Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental
   102  func (w *TxWriter) Write(ctx context.Context, messages ...Message) error {
   103  	return w.inner.Write(ctx, messages...)
   104  }
   105  
   106  // WaitInit waits until the reader is initialized
   107  // or an error occurs, return PublicInitialInfo and err
   108  //
   109  // Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental
   110  func (w *TxWriter) WaitInit(ctx context.Context) (err error) {
   111  	_, err = w.inner.WaitInit(ctx)
   112  	if err != nil {
   113  		return err
   114  	}
   115  
   116  	return nil
   117  }
   118  
   119  // WaitInitInfo waits until the reader is initialized
   120  // or an error occurs, return PublicInitialInfo and err
   121  //
   122  // Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental
   123  func (w *TxWriter) WaitInitInfo(ctx context.Context) (info PublicInitialInfo, err error) {
   124  	privateInfo, err := w.inner.WaitInit(ctx)
   125  	if err != nil {
   126  		return PublicInitialInfo{}, err
   127  	}
   128  	publicInfo := PublicInitialInfo{LastSeqNum: privateInfo.LastSeqNum}
   129  
   130  	return publicInfo, nil
   131  }