github.com/lirm/aeron-go@v0.0.0-20230415210743-920325491dc4/README.md (about)

     1  [![Build Status](https://travis-ci.org/lirm/aeron-go.svg?branch=master)](https://travis-ci.org/lirm/aeron-go)
     2  [![Go Report Card](https://goreportcard.com/badge/github.com/lirm/aeron-go)](https://goreportcard.com/report/github.com/lirm/aeron-go)
     3  [![Join the chat at https://gitter.im/aeron-go/Lobby](https://badges.gitter.im/aeron-go/Lobby.svg)](https://gitter.im/aeron-go/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
     4  <!--[![Coverage Status](https://coveralls.io/repos/github/lirm/aeron-go/badge.svg?branch=master)](https://coveralls.io/github/lirm/aeron-go?branch=master)-->
     5  
     6  # aeron-go
     7  
     8  Implementation of [Aeron](https://github.com/real-logic/Aeron) messaging client in Go.
     9  
    10  Architecture, design, and protocol of Aeron can be found [here](https://github.com/real-logic/Aeron/wiki)
    11  
    12  # Usage
    13  
    14  Example subscriber can be found [here](https://github.com/lirm/aeron-go/tree/master/examples/basic_subscriber).
    15  
    16  Example publication can be found [here](https://github.com/lirm/aeron-go/tree/master/examples/basic_publisher).
    17  
    18  ## Common
    19  
    20  Instantiate Aeron with Context:
    21  ```go
    22  ctx := aeron.NewContext().MediaDriverTimeout(time.Second * 10)
    23  
    24  a := aeron.Connect(ctx)
    25  ```
    26  
    27  ## Subscribers
    28  
    29  Create subscription:
    30  ```go
    31  subscription := <-a.AddSubscription("aeron:ipc", 10)
    32  
    33  defer subscription.Close()
    34  ```
    35  
    36  `aeron.AddSubscription()` returns a channel, so that the user has the choice
    37  of blocking waiting for subscription to register with the driver or do async `select` poll.
    38  
    39  Define callback for message processing:
    40  ```go
    41  handler := func(buffer *buffers.Atomic, offset int32, length int32, header *logbuffer.Header) {
    42      bytes := buffer.GetBytesArray(offset, length)
    43  
    44      fmt.Printf("Received a fragment with payload: %s\n", string(bytes))
    45  }
    46  ```
    47  
    48  Poll for messages:
    49  ```go
    50  idleStrategy := idlestrategy.Sleeping{time.Millisecond}
    51  
    52  for {
    53      fragmentsRead := subscription.Poll(handler, 10)
    54      idleStrategy.Idle(fragmentsRead)
    55  }
    56  ```
    57  
    58  ## Publications
    59  
    60  Create publication:
    61  ```go
    62  publication := <-a.AddPublication("aeron:ipc", 10)
    63  
    64  defer publication.Close()
    65  ```
    66  
    67  `aeron.AddPublication()` returns a channel, so that the user has the choice
    68  of blocking waiting for publication to register with the driver or do async `select` poll.
    69  
    70  Create Aeron buffer to send the message:
    71  ```go
    72  message := fmt.Sprintf("this is a message %d", counter)
    73  
    74  srcBuffer := buffers.MakeAtomic(([]byte)(message))
    75  ```
    76  
    77  Optionally make sure that there are connected subscriptions:
    78  ```go
    79  for !publication.IsConnected() {
    80      time.Sleep(time.Millisecond * 10)
    81  }
    82  ```
    83  
    84  Send the message, by calling `publication.Offer`
    85  ```go
    86  ret := publication.Offer(srcBuffer, 0, int32(len(message)), nil)
    87  switch ret {
    88  case aeron.NotConnected:
    89      log.Print("not connected yet")
    90  case aeron.BackPressured:
    91      log.Print("back pressured")
    92  default:
    93      if ret < 0 {
    94          log.Print("Unrecognized code: %d", ret)
    95      } else {
    96          log.Print("success!")
    97      }
    98  }
    99  ```