test: add an example for netpoll package

pkg/netpoll/example_netpoll_test.go

@@ -0,0 +1,154 @@
+/*
+ * Copyright (c) 2025 The Gnet Authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package netpoll_test
+
+import (
+	"context"
+	"log"
+	"net"
+	"os"
+	"os/signal"
+	"time"
+
+	"github.com/panjf2000/gnet/v2/pkg/errors"
+	"github.com/panjf2000/gnet/v2/pkg/netpoll"
+)
+
+func ExampleNetpoll() {
+	ln, err := net.Listen("tcp", "127.0.0.1:9090")
+	if err != nil {
+		log.Fatalf("Error listening: %v", err)
+	}
+
+	defer ln.Close()
+
+	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, os.Kill)
+	defer cancel()
+
+	go func() {
+		c, err := ln.Accept()
+		if err != nil {
+			log.Fatalf("Error accepting connection: %v", err)
+		}
+
+		defer c.Close()
+
+		buf := make([]byte, 64)
+
+		for {
+			select {
+			case <-ctx.Done():
+				cancel()
+				log.Printf("Signal received: %v", ctx.Err())
+				return
+			default:
+			}
+
+			_, err := c.Read(buf)
+			if err != nil {
+				log.Fatalf("Error reading data from client: %v", err)
+			}
+			log.Printf("Received data from client: %s", buf)
+
+			_, err = c.Write([]byte("Hello, client!"))
+			if err != nil {
+				log.Fatalf("Error writing data to client: %v", err)
+			}
+			log.Println("Sent data to client")
+
+			time.Sleep(200 * time.Millisecond)
+		}
+	}()
+
+	// Wait for the server to start running.
+	time.Sleep(500 * time.Millisecond)
+
+	poller, err := netpoll.OpenPoller()
+	if err != nil {
+		log.Fatalf("Error opening poller: %v", err)
+	}
+
+	defer poller.Close()
+
+	addr, err := net.ResolveTCPAddr("tcp", ln.Addr().String())
+	if err != nil {
+		log.Fatalf("Error resolving TCP address: %v", err)
+	}
+	c, err := net.DialTCP("tcp", nil, addr)
+	if err != nil {
+		log.Fatalf("Error dialing TCP address: %v", err)
+	}
+
+	f, err := c.File()
+	if err != nil {
+		log.Fatalf("Error getting file from connection: %v", err)
+	}
+
+	closeClient := func() {
+		c.Close()
+		f.Close()
+	}
+	defer closeClient()
+
+	sendData := true
+
+	pa := netpoll.PollAttachment{
+		FD: int(f.Fd()),
+		Callback: func(fd int, event netpoll.IOEvent, flags netpoll.IOFlags) error {
+			if netpoll.IsErrorEvent(event, flags) {
+				closeClient()
+				return errors.ErrEngineShutdown
+			}
+
+			if netpoll.IsReadEvent(event) {
+				buf := make([]byte, 64)
+				_, err := c.Read(buf)
+				if err != nil {
+					closeClient()
+					log.Println("Error reading data from server:", err)
+					return errors.ErrEngineShutdown
+				}
+				log.Printf("Received data from server: %s", buf)
+				sendData = true
+				// Process the data...
+			}
+
+			if netpoll.IsWriteEvent(event) && sendData {
+				sendData = false
+				// Write data to the connection...
+				_, err := c.Write([]byte("Hello, server!"))
+				if err != nil {
+					closeClient()
+					log.Println("Error writing data to server:", err)
+					return errors.ErrEngineShutdown
+				}
+				log.Println("Sent data to server")
+			}
+
+			return nil
+		}}
+
+	if err := poller.AddReadWrite(&pa, false); err != nil {
+		log.Fatalf("Error adding file descriptor to poller: %v", err)
+	}
+
+	err = poller.Polling(func(fd int, event netpoll.IOEvent, flags netpoll.IOFlags) error {
+		return pa.Callback(fd, event, flags)
+	})
+
+	log.Printf("Poller exited with error: %v", err)
+}

pkg/netpoll/netpoll.go

@@ -52,21 +52,23 @@ The OpenPoller function creates a new Poller instance:
 		c.Close()
 		f.Close()
 	}
+	defer closeClient()
 
 The PollAttachment consists of a file descriptor and its callback function.
 PollAttachment is used to register a file descriptor with the Poller.
 The callback function is called when an event occurs on the file descriptor:
 
 	pa := netpoll.PollAttachment{
 		FD: int(f.Fd()),
-		Callback: func(i int, event netpoll.IOEvent, flags netpoll.IOFlags) error {
+		Callback: func(fd int, event netpoll.IOEvent, flags netpoll.IOFlags) error {
 			if netpoll.IsErrorEvent(event, flags) {
 				closeClient()
 				return errors.ErrEngineShutdown
 			}
 
 			if netpoll.IsReadEvent(event) {
 				buf := make([]byte, 64)
+				// Read data from the connection.
 				_, err := c.Read(buf)
 				if err != nil {
 					closeClient()
@@ -76,7 +78,7 @@ The callback function is called when an event occurs on the file descriptor:
 			}
 
 			if netpoll.IsWriteEvent(event) {
-				// Write data to the connection...
+				// Write data to the connection.
 				_, err := c.Write([]byte("hello"))
 				if err != nil {
 					closeClient()
@@ -97,5 +99,11 @@ waiting for I/O events to occur:
 	poller.Polling(func(fd int, event netpoll.IOEvent, flags netpoll.IOFlags) error {
 		return pa.Callback(fd, event, flags)
 	})
+
+Or
+
+	poller.Polling()
+
+if you've enabled the build tag `poll_opt`.
 */
 package netpoll