Implement List{Offline,Online,Possible,Present} functions on Linux

numcpus.go

@@ -73,3 +73,26 @@ func GetPossible() (int, error) {
 func GetPresent() (int, error) {
 	return getPresent()
 }
+
+// ListOffline returns the list of offline CPUs. See [GetOffline] for details on
+// when a CPU is considered offline.
+func ListOffline() ([]int, error) {
+	return listOffline()
+}
+
+// ListOnline returns the list of CPUs that are online and being scheduled.
+func ListOnline() ([]int, error) {
+	return listOnline()
+}
+
+// ListPossible returns the list of possible CPUs. See [GetPossible] for
+// details on when a CPU is considered possible.
+func ListPossible() ([]int, error) {
+	return listPossible()
+}
+
+// ListPresent returns the list of present CPUs. See [GetPresent] for
+// details on when a CPU is considered present.
+func ListPresent() ([]int, error) {
+	return listPresent()
+}

numcpus_linux.go

@@ -24,7 +24,14 @@ import (
 	"golang.org/x/sys/unix"
 )
 
-const sysfsCPUBasePath = "/sys/devices/system/cpu"
+const (
+	sysfsCPUBasePath = "/sys/devices/system/cpu"
+
+	offline  = "offline"
+	online   = "online"
+	possible = "possible"
+	present  = "present"
+)
 
 func getFromCPUAffinity() (int, error) {
 	var cpuSet unix.CPUSet
@@ -34,19 +41,26 @@ func getFromCPUAffinity() (int, error) {
 	return cpuSet.Count(), nil
 }
 
-func readCPURange(file string) (int, error) {
+func readCPURangeWith[T any](file string, f func(cpus string) (T, error)) (T, error) {
+	var zero T
 	buf, err := os.ReadFile(filepath.Join(sysfsCPUBasePath, file))
 	if err != nil {
-		return 0, err
+		return zero, err
 	}
-	return parseCPURange(strings.Trim(string(buf), "\n "))
+	return f(strings.Trim(string(buf), "\n "))
 }
 
-func parseCPURange(cpus string) (int, error) {
+func countCPURange(cpus string) (int, error) {
+	// Treat empty file as valid. This might be the case if there are no offline CPUs in which
+	// case /sys/devices/system/cpu/offline is empty.
+	if cpus == "" {
+		return 0, nil
+	}
+
 	n := int(0)
 	for _, cpuRange := range strings.Split(cpus, ",") {
-		if len(cpuRange) == 0 {
-			continue
+		if cpuRange == "" {
+			return 0, fmt.Errorf("empty CPU range in CPU string %q", cpus)
 		}
 		from, to, found := strings.Cut(cpuRange, "-")
 		first, err := strconv.ParseUint(from, 10, 32)
@@ -69,6 +83,41 @@ func parseCPURange(cpus string) (int, error) {
 	return n, nil
 }
 
+func listCPURange(cpus string) ([]int, error) {
+	// See comment in countCPURange.
+	if cpus == "" {
+		return []int{}, nil
+	}
+
+	list := []int{}
+	for _, cpuRange := range strings.Split(cpus, ",") {
+		if cpuRange == "" {
+			return nil, fmt.Errorf("empty CPU range in CPU string %q", cpus)
+		}
+		from, to, found := strings.Cut(cpuRange, "-")
+		first, err := strconv.ParseUint(from, 10, 32)
+		if err != nil {
+			return nil, err
+		}
+		var last uint64
+		if found {
+			last, err = strconv.ParseUint(to, 10, 32)
+			if err != nil {
+				return nil, err
+			}
+		} else {
+			last = first
+		}
+		if last < first {
+			return nil, fmt.Errorf("last CPU in range (%d) less than first (%d)", last, first)
+		}
+		for cpu := int(first); cpu <= int(last); cpu++ {
+			list = append(list, cpu)
+		}
+	}
+	return list, nil
+}
+
 func getConfigured() (int, error) {
 	d, err := os.Open(sysfsCPUBasePath)
 	if err != nil {
@@ -104,20 +153,36 @@ func getKernelMax() (int, error) {
 }
 
 func getOffline() (int, error) {
-	return readCPURange("offline")
+	return readCPURangeWith(offline, countCPURange)
 }
 
 func getOnline() (int, error) {
 	if n, err := getFromCPUAffinity(); err == nil {
 		return n, nil
 	}
-	return readCPURange("online")
+	return readCPURangeWith(online, countCPURange)
 }
 
 func getPossible() (int, error) {
-	return readCPURange("possible")
+	return readCPURangeWith(possible, countCPURange)
 }
 
 func getPresent() (int, error) {
-	return readCPURange("present")
+	return readCPURangeWith(present, countCPURange)
+}
+
+func listOffline() ([]int, error) {
+	return readCPURangeWith(offline, listCPURange)
+}
+
+func listOnline() ([]int, error) {
+	return readCPURangeWith(online, listCPURange)
+}
+
+func listPossible() ([]int, error) {
+	return readCPURangeWith(possible, listCPURange)
+}
+
+func listPresent() ([]int, error) {
+	return readCPURangeWith(present, listCPURange)
 }

numcpus_linux_test.go

@@ -14,43 +14,145 @@
 
 package numcpus
 
-import "testing"
+import (
+	"reflect"
+	"testing"
+)
 
-func TestParseCPURange(t *testing.T) {
+func TestCPURange(t *testing.T) {
 	testCases := []struct {
-		str     string
-		n       int
-		wantErr bool
+		str       string
+		wantCount int
+		wantList  []int
+		wantErr   bool
 	}{
-		{str: "", n: 0},
-		{str: "0", n: 1},
-		{str: "0-1", n: 2},
-		{str: "1-1", n: 1},
-		{str: "0-7", n: 8},
-		{str: "1-7", n: 7},
-		{str: "1-15", n: 15},
-		{str: "0-3,7", n: 5},
-		{str: "0,2-4", n: 4},
-		{str: "0,2-4,7", n: 5},
-		{str: "0,2-4,7-15", n: 13},
-		{str: "0,2-4,6,8-10", n: 8},
-		{str: "invalid", n: 0, wantErr: true},
-		{str: "0-", n: 0, wantErr: true},
-		{str: "0-,1", n: 0, wantErr: true},
-		{str: "0,-3,5", n: 0, wantErr: true},
-		{str: "0,5-3", n: 0, wantErr: true},
+		{
+			str:       "",
+			wantCount: 0,
+			wantList:  []int{},
+		},
+		{
+			str:       "0",
+			wantCount: 1,
+			wantList:  []int{0},
+		},
+		{
+			str:       "0-1",
+			wantCount: 2,
+			wantList:  []int{0, 1},
+		},
+		{
+			str:       "1-1",
+			wantCount: 1,
+			wantList:  []int{1},
+		},
+		{
+			str:       "0-7",
+			wantCount: 8,
+			wantList:  []int{0, 1, 2, 3, 4, 5, 6, 7},
+		},
+		{
+			str:       "1-7",
+			wantCount: 7,
+			wantList:  []int{1, 2, 3, 4, 5, 6, 7},
+		},
+		{
+			str:       "1-15",
+			wantCount: 15,
+			wantList:  []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15},
+		},
+		{
+			str:       "0-3,7",
+			wantCount: 5,
+			wantList:  []int{0, 1, 2, 3, 7},
+		},
+		{
+			str:       "0,2-4",
+			wantCount: 4,
+			wantList:  []int{0, 2, 3, 4},
+		},
+		{
+			str:       "0,2-4,7",
+			wantCount: 5,
+			wantList:  []int{0, 2, 3, 4, 7},
+		},
+		{
+			str:       "0,2-4,7-15",
+			wantCount: 13,
+			wantList:  []int{0, 2, 3, 4, 7, 8, 9, 10, 11, 12, 13, 14, 15},
+		},
+		{
+			str:       "0,2-4,6,8-10,31",
+			wantCount: 9,
+			wantList:  []int{0, 2, 3, 4, 6, 8, 9, 10, 31},
+		},
+		{
+			str:     "invalid",
+			wantErr: true,
+		},
+		{
+			str:     "-",
+			wantErr: true,
+		},
+		{
+			str:     ",",
+			wantErr: true,
+		},
+		{
+			str:     ",1",
+			wantErr: true,
+		},
+		{
+			str:     "0,",
+			wantErr: true,
+		},
+		{
+			str:     "0-",
+			wantErr: true,
+		},
+		{
+			str:     "-15",
+			wantErr: true,
+		},
+		{
+			str:     "0-,1",
+			wantErr: true,
+		},
+		{
+			str:     "0,-3,5",
+			wantErr: true,
+		},
+		{
+			str:     "42-0",
+			wantErr: true,
+		},
+		{
+			str:     "0,5-3",
+			wantErr: true,
+		},
 	}
 
 	for _, tc := range testCases {
-		n, err := parseCPURange(tc.str)
+		count, err := countCPURange(tc.str)
 		if !tc.wantErr && err != nil {
-			t.Errorf("parseCPURange(%q) = %v, expected no error", tc.str, err)
+			t.Errorf("countCPURange(%q) = %v, expected no error", tc.str, err)
 		} else if tc.wantErr && err == nil {
-			t.Errorf("parseCPURange(%q) expected error", tc.str)
+			t.Errorf("countCPURange(%q) expected error", tc.str)
 		}
 
-		if n != tc.n {
-			t.Errorf("parseCPURange(%q) = %d, expected %d", tc.str, n, tc.n)
+		if count != tc.wantCount {
+			t.Errorf("countCPURange(%q) = %d, expected %d", tc.str, count, tc.wantCount)
+		}
+
+		list, err := listCPURange(tc.str)
+		if !tc.wantErr && err != nil {
+			t.Errorf("listCPURange(%q) = %v, expected no error", tc.str, err)
+		} else if tc.wantErr && err == nil {
+			t.Errorf("listCPURange(%q) expected error", tc.str)
+		}
+
+		if !reflect.DeepEqual(list, tc.wantList) {
+			t.Errorf("listCPURange(%q) = %d, expected %d", tc.str, list, tc.wantList)
 		}
 	}
 }
@@ -62,9 +164,9 @@ func TestGetFromCPUAffinity(t *testing.T) {
 	}
 
 	cpus := "online"
-	nSysfs, err := readCPURange(cpus)
+	nSysfs, err := readCPURangeWith(cpus, countCPURange)
 	if err != nil {
-		t.Fatalf("readCPURange(%q): %v", cpus, err)
+		t.Fatalf("counting CPU ranges from %q failed: %v", cpus, err)
 	}
 
 	if nAffinity != nSysfs {

numcpus_list_unsupported.go

@@ -0,0 +1,33 @@
+// Copyright 2024 Tobias Klauser
+//
+// 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.
+
+//go:build !linux
+
+package numcpus
+
+func listOffline() ([]int, error) {
+	return nil, ErrNotSupported
+}
+
+func listOnline() ([]int, error) {
+	return nil, ErrNotSupported
+}
+
+func listPossible() ([]int, error) {
+	return nil, ErrNotSupported
+}
+
+func listPresent() ([]int, error) {
+	return nil, ErrNotSupported
+}