New Issue: proposed: a reorganization of 'Sys' as part of module stabilization

Notifications Issues
#1

18448, "gbtitus", "proposed: a reorganization of 'Sys' as part of module stabilization", "2021-09-22T21:29:23Z"

Introduction

As part of module stabilization ("lib 2.0"), within the Chapel core team we've agreed upon a proposed reworking of the standard Sys module (chapel/Sys.chpl at main · chapel-lang/chapel · GitHub), which provides the operating system interface. This issue presents that proposal and asks for comments from the Chapel user community.

Details

There are three basic parts to the rework. First, there is a structural reorganization and renaming of the module itself. The current module is just called Sys, of course. We propose to replace this with a hierarchical module called OS. Then there are a couple of proposals about just what definitions the module will provide, and their style.

Proposal: Organization

The current Sys module will be renamed and reorganized as follows:

  • OS
    • POSIX
      • things defined by POSIX (the current Sys, though with adjustments)
      • includes POSIX things currently declared elsewhere, such as memcpy()
    • Linux
      • things defined by Linux but not POSIX
    • MacOS
      • things defined by macOS but not POSIX

Proposal: Style

The OS module and its sub-modules will provide C-style Chapel definitions matching the corresponding interface(s). Thus, for example, OS.POSIX will supply type, constant, variable, and function declarations that match the names, capitalization, layout (for structs), and signature (for functions) of the corresponding POSIX entities. Or in other words, it will provide a C-style interface rather than a "Chapel-tastic" one.

As a special case worth calling out, the OS.POSIX module will supply an errno "variable" that is like the POSIX one in that it is of type c_int, modifiable, and thread-local where "thread" means the underlying execution vehicle of a Chapel task. It is undefined whether the module errno is implemented by the module itself or refers directly to the underlying POSIX variable, and therefore undefined whether it may be set only as a side effect of calling functions defined in the module or also as a side effect of calling any POSIX function whatsoever, via some non-module route such as external C code linked with the program. It is also undefined how or when the relationship between language tasks and their underlying execution vehicle threads may change. For these reasons, reading the value of the OS.POSIX module errno variable should only be done immediately after a call to a function in the module itself, and writing its value should only be done immediately before a call to a function in the module.

Proposal: Contents

The initial OS.POSIX will include everything currently in Sys that is used somewhere in the Chapel module stack, as well as anything POSIX-related that is defined in other modules. We will adjust those other modules that refer to POSIX symbols to get their definitions from the OS.POSIX module. We may not include in OS.POSIX things that are defined by Sys but not used anywhere or (at implementor's discretion) not likely to be used soon.

Things currently defined in `Sys` that will certainly be defined in `OS.POSIX`.

The following are all the uses we currently see of the things defined in Sys.chpl. Note that where the Sys module's spelling, capitalization, etc. don't follow that of the proposed OS.POSIX module, the symbol names will change.

modules/internal/LocaleModelHelpSetup.chpl
  sys_getenv

modules/packages/Curl.chpl
  fd_set
  sys_fd_zero
  timeval
  Sys.sys_select

modules/packages/HDFS.chpl
  O_CREAT
  O_RDONLY
  O_RDWR
  O_TRUNC
  O_WRONLY

modules/standard/DateTime.chpl
  defines record timeval same as Sys does
  defines gettimeofday() as Sys would if it did (it doesn't)
  defines time_t same as Sys does
  defines localtime_r() as Sys would if it did (it doesn't)

modules/standard/IO.chpl
  Sys.sys_open (in comment)
  Sys.sys_connect (in comment)

modules/standard/Path.chpl
  sys_getenv()

modules/standard/Spawn.chpl
  sys_getenv()

modules/standard/SysBasic.chpl
  SOCK_STREAM (in comment)

modules/standard/Time.chpl
  timeval (in comment)

test/execflags/gbt/shell-meta-env.chpl
  sys_getenv()

test/io/ferguson/open-remote-string.chpl
  sys_getenv()

test/library/packages/HDF5/Hdf5PathHelp.chpl
  sys_getenv()

test/library/packages/HDFS/tzakian/HDFSiterator.chpl
  O_RDONLY

test/library/packages/HDFS/tzakian/chadoop.chpl
  O_RDONLY

test/library/packages/HDFS/tzakian/test.chpl
  O_RDONLY

test/library/standard/DateTime/testDatetimeTZ.chpl
  defines record timeval same as Sys does
  defines gettimeofday() as Sys would if it did (it doesn't)

test/runtime/configMatters/comm/ugni/SIGBUS-array-alloc.chpl
  sys_getenv()

test/runtime/configMatters/comm/ugni/SIGBUS-heap-extend.chpl
  sys_getenv()

test/types/records/diten/unusedExternRecordInProc.chpl
  defines record timeval same as Sys does

test/users/ferguson/sys/getenv/getenv.chpl
  sys_getenv()

In addition, FileSystem.chpl defines the following file mode bits that same as Sys.chpl would, but the definitions in the latter are commented out.

modules/standard/FileSystem.chpl
  S_IRUSR
  S_IWUSR
  S_IXUSR
  S_IRWXU
  S_IRGRP
  S_IWGRP
  S_IXGRP
  S_IRWXG
  S_IROTH
  S_IWOTH
  S_IXOTH
  S_IRWXO

Note that this detailed list does not reflect some ongoing work on a sockets library and therefore may need adjustment.