18448, "gbtitus", "proposed: a reorganization of 'Sys' as part of module stabilization", "2021-09-22T21:29:23Z"
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.
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.
Sys module will be renamed and reorganized as follows:
- things defined by POSIX (the current
Sys, though with adjustments)
- includes POSIX things currently declared elsewhere, such as
- things defined by POSIX (the current
- things defined by Linux but not POSIX
- things defined by macOS but not POSIX
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
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.
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()
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.