github.com/m3db/m3@v1.5.0/src/msg/producer/types.go (about)

     1  // Copyright (c) 2018 Uber Technologies, Inc.
     2  //
     3  // Permission is hereby granted, free of charge, to any person obtaining a copy
     4  // of this software and associated documentation files (the "Software"), to deal
     5  // in the Software without restriction, including without limitation the rights
     6  // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     7  // copies of the Software, and to permit persons to whom the Software is
     8  // furnished to do so, subject to the following conditions:
     9  //
    10  // The above copyright notice and this permission notice shall be included in
    11  // all copies or substantial portions of the Software.
    12  //
    13  // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    14  // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    15  // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    16  // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    17  // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    18  // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    19  // THE SOFTWARE.
    20  
    21  package producer
    22  
    23  import (
    24  	"github.com/m3db/m3/src/cluster/services"
    25  )
    26  
    27  // FinalizeReason defines the reason why the message is being finalized by Producer.
    28  type FinalizeReason int
    29  
    30  const (
    31  	// Consumed means the message has been fully consumed.
    32  	Consumed FinalizeReason = iota
    33  
    34  	// Dropped means the message has been dropped.
    35  	Dropped
    36  )
    37  
    38  // Message contains the data that will be produced by the producer.
    39  // It should only be finalized by the producer.
    40  type Message interface {
    41  	// Shard returns the shard of the message.
    42  	Shard() uint32
    43  
    44  	// Bytes returns the bytes of the message.
    45  	Bytes() []byte
    46  
    47  	// Size returns the size of the bytes of the message.
    48  	Size() int
    49  
    50  	// Finalize will be called by producer to indicate the end of its lifecycle.
    51  	Finalize(FinalizeReason)
    52  }
    53  
    54  // CloseType decides how the producer should be closed.
    55  type CloseType int
    56  
    57  const (
    58  	// WaitForConsumption blocks the close call until all the messages have been consumed.
    59  	WaitForConsumption CloseType = iota
    60  	// DropEverything will close the producer and drop all the messages that have not been consumed.
    61  	DropEverything
    62  )
    63  
    64  // Producer produces message to a topic.
    65  type Producer interface {
    66  	// Produce produces the message.
    67  	Produce(m Message) error
    68  
    69  	// RegisterFilter registers a filter to a consumer service.
    70  	RegisterFilter(sid services.ServiceID, fn FilterFunc)
    71  
    72  	// UnregisterFilter unregisters the filter of a consumer service.
    73  	UnregisterFilter(sid services.ServiceID)
    74  
    75  	// NumShards returns the total number of shards of the topic the producer is
    76  	// producing to.
    77  	NumShards() uint32
    78  
    79  	// Init initializes a producer.
    80  	Init() error
    81  
    82  	// Close stops the producer from accepting new requests immediately.
    83  	// If the CloseType is WaitForConsumption, then it will block until all the messages have been consumed.
    84  	// If the CloseType is DropEverything, then it will simply drop all the messages buffered and return.
    85  	Close(ct CloseType)
    86  }
    87  
    88  // FilterFunc can filter message.
    89  type FilterFunc func(m Message) bool
    90  
    91  // Options configs a producer.
    92  type Options interface {
    93  	// Buffer returns the buffer.
    94  	Buffer() Buffer
    95  
    96  	// SetBuffer sets the buffer.
    97  	SetBuffer(value Buffer) Options
    98  
    99  	// Writer returns the writer.
   100  	Writer() Writer
   101  
   102  	// SetWriter sets the writer.
   103  	SetWriter(value Writer) Options
   104  }
   105  
   106  // Buffer buffers all the messages in the producer.
   107  type Buffer interface {
   108  	// Add adds message to the buffer and returns a reference counted message.
   109  	Add(m Message) (*RefCountedMessage, error)
   110  
   111  	// Init initializes the buffer.
   112  	Init()
   113  
   114  	// Close stops the buffer from accepting new requests immediately.
   115  	// If the CloseType is WaitForConsumption, then it will block until all the messages have been consumed.
   116  	// If the CloseType is DropEverything, then it will simply drop all the messages buffered and return.
   117  	Close(ct CloseType)
   118  }
   119  
   120  // Writer writes all the messages out to the consumer services.
   121  type Writer interface {
   122  	// Write writes a reference counted message out.
   123  	Write(rm *RefCountedMessage) error
   124  
   125  	// RegisterFilter registers a filter to a consumer service.
   126  	RegisterFilter(sid services.ServiceID, fn FilterFunc)
   127  
   128  	// UnregisterFilter unregisters the filter of a consumer service.
   129  	UnregisterFilter(sid services.ServiceID)
   130  
   131  	// NumShards returns the total number of shards of the topic the writer is
   132  	// writing to.
   133  	NumShards() uint32
   134  
   135  	// Init initializes a writer.
   136  	Init() error
   137  
   138  	// Close closes the writer.
   139  	Close()
   140  }