feat: export the core internal packages (#667)

acceptor_unix.go

@@ -22,10 +22,10 @@ import (
 
 	"golang.org/x/sys/unix"
 
-	"github.com/panjf2000/gnet/v2/internal/netpoll"
-	"github.com/panjf2000/gnet/v2/internal/queue"
-	"github.com/panjf2000/gnet/v2/internal/socket"
 	"github.com/panjf2000/gnet/v2/pkg/errors"
+	"github.com/panjf2000/gnet/v2/pkg/netpoll"
+	"github.com/panjf2000/gnet/v2/pkg/queue"
+	"github.com/panjf2000/gnet/v2/pkg/socket"
 )
 
 func (el *eventloop) accept0(fd int, _ netpoll.IOEvent, _ netpoll.IOFlags) error {

client_unix.go

@@ -27,13 +27,13 @@ import (
 	"golang.org/x/sync/errgroup"
 	"golang.org/x/sys/unix"
 
-	"github.com/panjf2000/gnet/v2/internal/math"
-	"github.com/panjf2000/gnet/v2/internal/netpoll"
-	"github.com/panjf2000/gnet/v2/internal/queue"
-	"github.com/panjf2000/gnet/v2/internal/socket"
 	"github.com/panjf2000/gnet/v2/pkg/buffer/ring"
 	errorx "github.com/panjf2000/gnet/v2/pkg/errors"
 	"github.com/panjf2000/gnet/v2/pkg/logging"
+	"github.com/panjf2000/gnet/v2/pkg/math"
+	"github.com/panjf2000/gnet/v2/pkg/netpoll"
+	"github.com/panjf2000/gnet/v2/pkg/queue"
+	"github.com/panjf2000/gnet/v2/pkg/socket"
 )
 
 // Client of gnet.

connection_bsd.go

@@ -22,7 +22,7 @@ import (
 
 	"golang.org/x/sys/unix"
 
-	"github.com/panjf2000/gnet/v2/internal/netpoll"
+	"github.com/panjf2000/gnet/v2/pkg/netpoll"
 )
 
 func (c *conn) processIO(_ int, filter netpoll.IOEvent, flags netpoll.IOFlags) (err error) {

connection_linux.go

@@ -22,7 +22,7 @@ import (
 
 	"golang.org/x/sys/unix"
 
-	"github.com/panjf2000/gnet/v2/internal/netpoll"
+	"github.com/panjf2000/gnet/v2/pkg/netpoll"
 )
 
 func (c *conn) processIO(_ int, ev netpoll.IOEvent, _ netpoll.IOFlags) error {

connection_unix.go

@@ -25,16 +25,16 @@ import (
 
 	"golang.org/x/sys/unix"
 
-	"github.com/panjf2000/gnet/v2/internal/bs"
 	"github.com/panjf2000/gnet/v2/internal/gfd"
-	gio "github.com/panjf2000/gnet/v2/internal/io"
-	"github.com/panjf2000/gnet/v2/internal/netpoll"
-	"github.com/panjf2000/gnet/v2/internal/queue"
-	"github.com/panjf2000/gnet/v2/internal/socket"
+	"github.com/panjf2000/gnet/v2/pkg/bs"
 	"github.com/panjf2000/gnet/v2/pkg/buffer/elastic"
 	errorx "github.com/panjf2000/gnet/v2/pkg/errors"
+	gio "github.com/panjf2000/gnet/v2/pkg/io"
 	"github.com/panjf2000/gnet/v2/pkg/logging"
+	"github.com/panjf2000/gnet/v2/pkg/netpoll"
 	bsPool "github.com/panjf2000/gnet/v2/pkg/pool/byteslice"
+	"github.com/panjf2000/gnet/v2/pkg/queue"
+	"github.com/panjf2000/gnet/v2/pkg/socket"
 )
 
 type conn struct {

engine_unix.go

@@ -27,10 +27,10 @@ import (
 	"golang.org/x/sync/errgroup"
 
 	"github.com/panjf2000/gnet/v2/internal/gfd"
-	"github.com/panjf2000/gnet/v2/internal/netpoll"
-	"github.com/panjf2000/gnet/v2/internal/queue"
 	errorx "github.com/panjf2000/gnet/v2/pkg/errors"
 	"github.com/panjf2000/gnet/v2/pkg/logging"
+	"github.com/panjf2000/gnet/v2/pkg/netpoll"
+	"github.com/panjf2000/gnet/v2/pkg/queue"
 )
 
 type engine struct {

eventloop_unix.go

@@ -28,11 +28,11 @@ import (
 
 	"golang.org/x/sys/unix"
 
-	gio "github.com/panjf2000/gnet/v2/internal/io"
-	"github.com/panjf2000/gnet/v2/internal/netpoll"
-	"github.com/panjf2000/gnet/v2/internal/queue"
 	errorx "github.com/panjf2000/gnet/v2/pkg/errors"
+	gio "github.com/panjf2000/gnet/v2/pkg/io"
 	"github.com/panjf2000/gnet/v2/pkg/logging"
+	"github.com/panjf2000/gnet/v2/pkg/netpoll"
+	"github.com/panjf2000/gnet/v2/pkg/queue"
 )
 
 type eventloop struct {
@@ -238,11 +238,11 @@ func (el *eventloop) close(c *conn, err error) error {
 		if len(iov) > iovMax {
 			iov = iov[:iovMax]
 		}
-		if n, e := gio.Writev(c.fd, iov); e != nil {
+		n, err := gio.Writev(c.fd, iov)
+		if err != nil {
 			break
-		} else { //nolint:revive
-			_, _ = c.outboundBuffer.Discard(n)
 		}
+		_, _ = c.outboundBuffer.Discard(n)
 	}
 
 	c.release()

gnet.go

@@ -12,6 +12,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package gnet implements a high-performance, lightweight, non-blocking,
+// event-driven networking framework written in pure Go.
+//
+// Visit https://gnet.host/ for more details about gnet.
 package gnet
 
 import (
@@ -23,10 +27,10 @@ import (
 	"sync"
 	"time"
 
-	"github.com/panjf2000/gnet/v2/internal/math"
 	"github.com/panjf2000/gnet/v2/pkg/buffer/ring"
 	"github.com/panjf2000/gnet/v2/pkg/errors"
 	"github.com/panjf2000/gnet/v2/pkg/logging"
+	"github.com/panjf2000/gnet/v2/pkg/math"
 )
 
 // Action is an action that occurs after the completion of an event.

listener_unix.go

@@ -25,10 +25,10 @@ import (
 
 	"golang.org/x/sys/unix"
 
-	"github.com/panjf2000/gnet/v2/internal/netpoll"
-	"github.com/panjf2000/gnet/v2/internal/socket"
 	"github.com/panjf2000/gnet/v2/pkg/errors"
 	"github.com/panjf2000/gnet/v2/pkg/logging"
+	"github.com/panjf2000/gnet/v2/pkg/netpoll"
+	"github.com/panjf2000/gnet/v2/pkg/socket"
 )
 
 type listener struct {

load_balancer.go

@@ -18,7 +18,7 @@ import (
 	"hash/crc32"
 	"net"
 
-	"github.com/panjf2000/gnet/v2/internal/bs"
+	"github.com/panjf2000/gnet/v2/pkg/bs"
 )
 
 // LoadBalancing represents the type of load-balancing algorithm.

internal/bs/bs.go → pkg/bs/bs.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package bs provides a few handy bytes/string functions.
 package bs
 
 import (

pkg/buffer/elastic/elastic_ring_buffer.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package elastic implements an elastic ring-buffer.
 package elastic
 
 import (

pkg/buffer/linkedlist/linked_list_buffer.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package linkedlist implements a memory-reusable linked list of byte slices.
 package linkedlist
 
 import (

pkg/buffer/ring/ring_buffer.go

@@ -18,14 +18,15 @@
 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 
+// Package ring implements a memory-efficient circular buffer.
 package ring
 
 import (
 	"errors"
 	"io"
 
-	"github.com/panjf2000/gnet/v2/internal/bs"
-	"github.com/panjf2000/gnet/v2/internal/math"
+	"github.com/panjf2000/gnet/v2/pkg/bs"
+	"github.com/panjf2000/gnet/v2/pkg/math"
 	bsPool "github.com/panjf2000/gnet/v2/pkg/pool/byteslice"
 )
 

pkg/errors/errors.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package errors defines common errors for gnet.
 package errors
 
 import "errors"

pkg/io/io.go

@@ -0,0 +1,18 @@
+/*
+ * 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 io provides some handy network I/O functions.
+package io

internal/math/math.go → pkg/math/math.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package math provides a few fast math functions.
 package math
 
 const (

internal/netpoll/defs_poller_epoll.go → pkg/netpoll/defs_poller_epoll.go

@@ -40,10 +40,25 @@ const (
 	WriteEvents = unix.EPOLLOUT
 	// ReadWriteEvents represents both readable and writeable events.
 	ReadWriteEvents = ReadEvents | WriteEvents
-	// ErrEvents represents exceptional events that occurred on the local side.
+	// ErrEvents represents exceptional events that occurred.
 	ErrEvents = unix.EPOLLERR | unix.EPOLLHUP
 )
 
+// IsReadEvent checks if the event is a read event.
+func IsReadEvent(event IOEvent) bool {
+	return event&ReadEvents != 0
+}
+
+// IsWriteEvent checks if the event is a write event.
+func IsWriteEvent(event IOEvent) bool {
+	return event&WriteEvents != 0
+}
+
+// IsErrorEvent checks if the event is an error event.
+func IsErrorEvent(event IOEvent, _ IOFlags) bool {
+	return event&ErrEvents != 0
+}
+
 type eventList struct {
 	size   int
 	events []epollevent

internal/netpoll/defs_poller_kqueue.go → pkg/netpoll/defs_poller_kqueue.go

@@ -28,8 +28,31 @@ const (
 	MinPollEventsCap = 16
 	// MaxAsyncTasksAtOneTime is the maximum amount of asynchronous tasks that the event-loop will process at one time.
 	MaxAsyncTasksAtOneTime = 128
+	// ReadEvents represents readable events that are polled by kqueue.
+	ReadEvents = unix.EVFILT_READ
+	// WriteEvents represents writeable events that are polled by kqueue.
+	WriteEvents = unix.EVFILT_WRITE
+	// ReadWriteEvents represents both readable and writeable events.
+	ReadWriteEvents = ReadEvents | WriteEvents
+	// ErrEvents represents exceptional events that occurred.
+	ErrEvents = unix.EV_EOF | unix.EV_ERROR
 )
 
+// IsReadEvent checks if the event is a read event.
+func IsReadEvent(event IOEvent) bool {
+	return event == ReadEvents
+}
+
+// IsWriteEvent checks if the event is a write event.
+func IsWriteEvent(event IOEvent) bool {
+	return event == WriteEvents
+}
+
+// IsErrorEvent checks if the event is an error event.
+func IsErrorEvent(_ IOEvent, flags IOFlags) bool {
+	return flags&ErrEvents != 0
+}
+
 type eventList struct {
 	size   int
 	events []unix.Kevent_t

pkg/netpoll/netpoll.go

@@ -0,0 +1,101 @@
+/*
+ * 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 provides a portable event-driven interface for network I/O.
+
+The underlying facility of event notification is OS-specific:
+  - epoll on Linux - https://man7.org/linux/man-pages/man7/epoll.7.html
+  - kqueue on *BSD/Darwin - https://man.freebsd.org/cgi/man.cgi?kqueue
+
+With the help of the netpoll package, you can easily build your own high-performance
+event-driven network applications based on epoll/kqueue.
+
+The Poller represents the event notification facility whose backend is epoll or kqueue.
+The OpenPoller function creates a new Poller instance:
+
+	poller, err := netpoll.OpenPoller()
+	if err != nil {
+		// handle error
+	}
+
+	defer poller.Close()
+
+	addr, err := net.ResolveTCPAddr("tcp", "127.0.0.1:9090")
+	if err != nil {
+		// handle error
+	}
+	c, err := net.DialTCP("tcp", nil, addr)
+	if err != nil {
+		// handle error
+	}
+
+	f, err := c.File()
+	if err != nil {
+		// handle error
+	}
+
+	closeClient := func() {
+		c.Close()
+		f.Close()
+	}
+
+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 {
+			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()
+					return errors.ErrEngineShutdown
+				}
+				// Process the data...
+			}
+
+			if netpoll.IsWriteEvent(event) {
+				// Write data to the connection...
+				_, err := c.Write([]byte("hello"))
+				if err != nil {
+					closeClient()
+					return errors.ErrEngineShutdown
+				}
+			}
+
+			return nil
+		}}
+
+	if err := poller.AddReadWrite(&pa, false); err != nil {
+		// handle error
+	}
+
+The Poller.Polling function starts the event loop monitoring file descriptors and
+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)
+	})
+*/
+package netpoll