1 // pubsubplus-go-client 2 // 3 // Copyright 2021-2024 Solace Corporation. All rights reserved. 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); 6 // you may not use this file except in compliance with the License. 7 // You may obtain a copy of the License at 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 11 // Unless required by applicable law or agreed to in writing, software 12 // distributed under the License is distributed on an "AS IS" BASIS, 13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 // See the License for the specific language governing permissions and 15 // limitations under the License. 16 17 package solace 18 19 import "time" 20 21 // LifecycleControl contains lifecycle functionality common to 22 // various messaging services such as publishers and receivers. 23 type LifecycleControl interface { 24 // Start starts the messaging service synchronously. 25 // Before this function is called, the messaging service is considered 26 // off-duty. To operate normally, this function must be called on 27 // a receiver or publisher instance. This function is idempotent. 28 // Returns an error if one occurred or nil if successful. 29 Start() error 30 31 // StartAsync starts the messaging service asynchronously. 32 // Before this function is called, the messaging service is considered 33 // off-duty. To operate normally, this function must be called on 34 // a receiver or publisher instance. This function is idempotent. 35 // Returns a channel that will receive an error if one occurred or 36 // nil if successful. Subsequent calls will return additional 37 // channels that can await an error, or nil if already started. 38 StartAsync() <-chan error 39 40 // Terminate terminates the messaging service gracefully and synchronously. 41 // This function is idempotent. The only way to resume operation 42 // after this function is called is to create another instance. 43 // Any attempt to call this function renders the instance 44 // permanently terminated, even if this function completes. 45 // A graceful shutdown is attempted within the specified grace period (gracePeriod). 46 // Setting gracePeriod to 0 implies a non-graceful shutdown that ignores 47 // unfinished tasks or in-flight messages. 48 // This function returns an error if one occurred, or 49 // nil if it successfully and gracefully terminated. 50 // If gracePeriod is set to less than 0, the function waits indefinitely. 51 Terminate(gracePeriod time.Duration) error 52 53 // TerminateAsync terminates the messaging service asynchronously. 54 // This function is idempotent. The only way to resume operation 55 // after this function is called is to create another instance. 56 // Any attempt to call this function renders the instance 57 // permanently terminated, even if this function completes. 58 // A graceful shutdown is attempted within the specified grace period (gracePeriod). 59 // Setting gracePeriod to 0 implies a non-graceful shutdown that ignores 60 // unfinished tasks or in-flight messages. 61 // This function returns a channel that receives an error if one occurred, or 62 // nil if it successfully and gracefully terminated. 63 // If gracePeriod is set to less than 0, the function waits indefinitely. 64 TerminateAsync(gracePeriod time.Duration) <-chan error 65 66 // IsRunning checks if the process was successfully started and not yet stopped. 67 // Returns true if running, otherwise false. 68 IsRunning() bool 69 70 // IsTerminates checks if the message-delivery process is terminated. 71 // Returns true if terminated, otherwise false. 72 IsTerminated() bool 73 74 // IsTerminating checks if the message-delivery process termination is ongoing. 75 // Returns true if the message message-delivery process is being terminated, 76 // but termination is not yet complete, otherwise false. 77 IsTerminating() bool 78 79 // SetTerminationNotificationListener adds a callback to listen for 80 // non-recoverable interruption events. 81 SetTerminationNotificationListener(listener TerminationNotificationListener) 82 } 83 84 // TerminationNotificationListener represents a listener that can be 85 // registered with a LifecycleControl instance to listen for 86 // termination events. 87 type TerminationNotificationListener func(TerminationEvent) 88 89 // TerminationEvent represents a non-recoverable receiver or publisher 90 // unsolicited termination for which applications can listen. 91 type TerminationEvent interface { 92 // GetTimestamp retrieves the timestamp of the event. 93 GetTimestamp() time.Time 94 // GetMessage retrieves the event message. 95 GetMessage() string 96 // GetCause retrieves the cause of the client exception, if any. 97 // Returns the error event or nil if no cause is present. 98 GetCause() error 99 } 100