crate: annotate unstable *MAX constants#5122
Open
dybucc wants to merge 1 commit into
Open
Conversation
dybucc
changed the title
*MAX constants fitting rust-lang/libc#3131
dybucc
changed the title
*MAX constants fitting rust-lang/libc#3131*MAX constants fitting #3131
dybucc
force-pushed
the
_max-deprecation
branch
11 times, most recently
from
5ee0951 to
3bc30cb
Compare
3 tasks
dybucc
force-pushed
the
_max-deprecation
branch
2 times, most recently
from
cb9c814 to
0141e49
Compare
This comment has been minimized.
This comment has been minimized.
3 tasks
This comment has been minimized.
This comment has been minimized.
Contributor
Author
|
CI actually passes. There seems to be an issue with a glob import that is not used, but this has not |
rustbot
added
the
stable-nominated
This comment has been minimized.
This comment has been minimized.
3 tasks
This comment has been minimized.
This comment has been minimized.
Contributor
|
For updating doc comments like the others, @rustbot author |
Collaborator
|
Reminder, once the PR becomes ready for a review, use |
This comment has been minimized.
This comment has been minimized.
Collaborator
|
This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed. Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers. |
There were troublesome symbols. Upstrem releases can change them. The frequency of change is inconvenient. This makes SemVer inconvenient. Users may need advice. This patch does that.
dybucc
changed the title
*MAX constants fitting #3131*MAX constants
Contributor
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR adds documentation. This affects certain symbols. These are often not stable upstream. This causes SemVer-breaking issues. Users may need advice. This patch links to such advice.
Some constants have been ignored. They are issued to
sysconf.POSIX defines clases of constants. They are part of
limits.h. Some are runtime invariant. Others are not. Numerical limits have been skipped. Runtime invariant values have been skipped. Pathname variable values have been annotated. Runtime increasable values have been annotated.POSIX-compliance has been assumed. This is sometimes broken. NetBSD is an example. They define
AIO_LIST_MAXas variable [1.] This should be a runtime invariant value. This PR does not handle this.QNX sources have not been found. Its module has been barely modified. Only some symbols have been taken into consideration. Those correspond with the above POSIX-defined symbols.
Sources
ELIBMAXis not the type of constant we would want to deprecate. This is just another enum-like "variant" forerrnovalues. A concise defintion of its purpose is given in the below source, though this is not exclusive to Hermit.Hexagon sources show that
SIGRTMAXmay be the type of constant we want to deprecate (sources can be found on the downloadable SDK.) This constant exists for the purposes of keeping a higher limit on the number of realtime signals that the system can issue. In theory, this is not defined inlimits.h, and very much seems like a fitting "limit" value to be deprecated, but I have my doubts. Either way, this patch deprecates it.Linux sources show that the
J1939_FILTER_MAXconstant may be the type of symbol we would want to deprecate. Even though there's other_MAX-suffixed symbols in that module, the comment left alongside this one in the source code seems fitting of a "limit" value. This constant is documented in the kernel as being an upper limit on the number of filters that the J1939 protocol over CAN can configure. Considering the protocol is a higher-level abstraction, I am not sure if we can assume a certain degree of stability here, so I've deprecated it. But then again, I have my doubts.NetBSD sources show that the
MOD_PPSMAXconstant is likely not one we would want to deprecate, as judging solely by the inline comment left alongside the symbol definition, it is meant to be used as an identifier to set an upper limit on some system config.Linux sources show that, much like the above limit on filters for the J1939 protocol over CAN, the
CAN_RAW_FILTER_MAXconstant may be worth deprecating, as it seems to set the upper bound on the number of filters that one can set over raw CAN with astruct can_filter.Hexagon sources show that the
TMP_MAXandFOPEN_MAXconstants are very similar to those symbols I decided not to deprecate in thelimits.hheader file of each target system's implementation. Their documentation in the downloadable SDK use the same wording and express the same purpose as other constants inlimits.h, so I decided against deprecating those. These are actually part of SUSv2 (thoughFOPEN_MAXprevails in current versions of the standard,) and are supposed to be runtime invariant, so a user does not really risk anything by reading them through the value exposed inlimits.hor otherwise through thesysconflibrary routine with the corresponding_SC-prefixed constants.All of the TeeOS
_MAX-suffixed constants are part of those defined as the implementation limits for POSIX-defined constants, so those have not been modified. The same applies to a bunch of other implementations, such as those declared by the QuRT in theirlimits.hheader file. At the moment, though, this only applies to those constants that have been known to be runtime invariant by any one of the SUSv2, SUSv3 or the latest POSIX standard specifications.The
RLIM_SAVED_MAXconstant, even though not quite the same as the other limits, is documented in The Linux Programming Interface, by Michael Kerrisk, as being a similar resource limit for applications where, say, one may have launched a process on some machine where a 64-bit resource limit is inherited but the process is being run in 32-bit mode (e.g. x86_32) is only capable of holding a potentially smaller resource limit. I believe this is not the type of constant we would want to deprecate.The BSD folks seem to do things a bit differently when it comes to limits that are used for kernel-relative requests to
sysctl, but that does not mean the constants defined analogously to those in thelimits.hheader file have a different purpose (for the most part.) That's why I've decided against deprecating those we expose in thelibccrate; Namely,KERN_IOV_MAXandKERN_ARGMAX. One exception to this is theKERN_SBMAXconstant, which is not defined in terms of a constant in the POSIX standard, but the accompanying comments in the NetBSD source mentions as being used for the maximum size of a socket buffer; I've thus left it undeprecated.The same applies to some of the
USER_- andCTL_-prefixed symbols. In this group, we do expose some constants that without the prefix actually match runtime increasable symbols specified in the POSIX standards.The
FILENAME_MAXconstant has not been deprecated, as that one seems to be part of the C standard library and seems to denote the largest supported character in an array of Cchars. This likely makes it something folks can just read up, as there's nosysconfor (more appropiately, in this instance)pathconfconstant to issue to these library routines to check the sure limit at runtime.The
RTAX_MAXconstant, unlike those mentioned above for the BSDs, is the type of limit we would want to deprecate, as it really only gives a size limit for arrays that are meant to hold all of thesockaddrvalues that are declared before it in the sources.The
NFSMNT_ACREGMAXandNFSMNT_ACDIRMAXconstants are likely not the type of symbols we would want to deprecate, as those provide information in OpenBSD to fix the values of the last fields of thestruct nfs_args. Though while looking into the source, I noticed we also expose from thelibccrate theNFS_ARGSVERSIONconstant, which is documented as changing whenever the afore mentioned record changes. This is quite definetely worth deprecating, and this patch does so.The FreeBSD sources show that the
CMGROUP_MAXconstant is likely not meant for deprecation, as the comment alongside its definition mentions that it's meant to be a limit on an actual resource and (to some extent) has historical significance. I believe this is not the type of constant that would be prone to fast changes, so I haven't deprecated it.I am not completely sure of the
RTP_PRIO_MAXconstant in FreeBSD. It seems to denote the type of range fitting the constants we are deprecating, but it does seem to be used across the codebase to fix values relating to thertpriofamily of functions. For the time being, I've left it undeprecated.The
MOD_PPSMAXconstant is not fit for deprecation, as it's used as a "variant" for setter routine in the FreeBSD source.The
SYS_-prefixed constants in Android are not meant for deprecation either. Those are used as "variants" to be issued tosyscall()such that they may serve as identifiers for some other piece of functionality.I'm having doubts about the
PRIO_MAXconstant in the Fuchsia and GNU Hurd trees. At first, I thought it would be part of constants defined in the POSIX standard likeMQ_PRIO_MAX, where I decided against their deprecation so long as they were noted as runtime invariant in the spec. But looking at the Fuchsia source code, I am not so sure; It seems to be defined for compatibility with the Android Bionic source code judging by the file hierarchy, but it is not declared alongside other constants I would rather not deprecate. I would like some input on this from somebody else.I couldn't get hold of the AIX sources, but I assumed the same of the
RTAX_MAXconstant as I did in the BSDs, and went ahead and deprecated it. I could be wrong, though, as I've not had access to the upstream code. The same can be said of theBC_- andCOL_-prefixed constants, both of which exist under the BSDs with an additionalUSER_prefix. See the comments on those above. This also applies to theSIGRTMAXconstant, which I did deprecate, as commented with the Hexagon sources above, and as explained in The Linux Programming Interface book.The
AF_MAXandPF_MAXconstants have been deprecated across all targets, as they seem to be used to denote the current limit on the procol and adress families after all otherAF_- andPF_-prefixed constants.A constant that had breen previously marked as deprecated,
AIO_LISTIO_MAX, has been undeprecated in favor of keeping deprecated solely the set of constants that are not runtime invariant according to the POSIX standard. This was discussed in the Notes section above.The
SO_TS_CLOCK_MAXconstant has been deprecated though it may just be that it should not be deprecated. This constant appears to me in the FreeBSD source code as being used solely for the purposes of denoting the largest of the constants defined prior to it, except forSO_TS_DEFAULT, which itself also takes on the values of one of the constants defined before it. I've taken this to mean that it's a "limit" value of the type we seek to deprecate. There's no mention of it in the POSIX standards either, so I've had to take a desision here that may have been the wrong one.The
CPU_STATE_MAXconstant in the XNU kernel was deprecated as it seems to be used as the maximum value that the possible CPU states can take on. Below its definition, the actual states are declared, with its own definition rounding up the size for, say, an array of such states.The
SCOPE6_ID_MAXconstant in the XNU kernel has not been deprecated because it does not seem like it is a limit of any sort. There's neither any documentation on it beyond the comment left alongside its definition, which does not imply such use.I couldn't get any information on the
SC_SPCM_MAXconstant, because that is declared solely in AIX, and I can't get my hands on any AIX source code.I couldn't pinpoint the
PR_SME_VL_LEN_MAXconstant in the glibc repo, but I've decided against its depreaction because of the context that the kernel docs provide on similar constants (apparently related to vectored matrix operations on AArch64.) From my read on some of the sections (especially Section 6,) I believe this constant to be used as the maximum length of the SME vector length. This does not strike me like the type of "limit" we're trying to deprecate.After looking into the
IN_CLASSA_MAXandIN_CLASSB_MAXconstants in the GNU Hurd, I couldn't find those to be constants that we would want to deprecate, though in this particular instance, I would greatly appreciate if somebody else checked things out.I am not sure about deprecating the
__SIGRTMAXconstant in the GNU Hurd. This constant should be deprecated if we follow the same reasoning as explained in one of the above items. But this symbol is documented in the upstream source code as not being something users should call from application code. They should instead useSIGRTMAXas defined insignal.h. That one definition, though, we do not expose in thelibccrate. I don't think the solution goes through adding that one constant and immediately deprecating it.I couldn't locate the
TCP_COOKIE_MAXin the GNU Hurd codebase, so I've left it unmodified as I can't quite determine whether it should be deprecated or not without further context, and it does not seem to appear in any other supported target system.The
RTLD_DI_MAXconstant got deprecated, even though I couldn't locate it in the GNU Hurd source code, because that one has documentation on the constants that are declared right before it in the Linux manpages. I then assumed that the fact it takes on the largest value of such enum-like constants was enough to represent a "limit" constant prone to SemVer breakage.The following Android and Linux constants:
NFQA_CFG_F_MAX,__NFT_REG_MAX,NFT_MSG_MAX,INPUT_PROP_MAX,FF_MAX,EV_MAX,SYN_MAX,KEY_MAX,REL_MAX,ABS_MAX,SW_MAXMSC_MAX,LED_MAX,REP_MAX,SND_MAX,PR_SCHED_CORE_MAX,KERN_PIDMAX,KERN_NGROUPS_MAX(no source because it's part of the runtime increasable values in POSIX)got deprecated following from the fact each of them are used as trailing enum values for the largest value of the constants whose suffix is not
MAX.The
PROP_VALUE_MAXconstant in the Android source code did not get deprecated, as that seems to be meant for a limit on the length of some higher-level abstraction (judging by the comments left in the comments alongside it.) A related constant,PROP_NAME_MAX, serves a similar purpose and has not been deprecated, but may just be fit for deprecation as the Android sources themselves mention so in an accompanying comment.The
KERN_SHMMAXconstant in the Android source tree is likely not meant to be deprecated. Even though not explicitly included among the runtime invariant values specified in POSIX, its use upstream does not seem like that of a "limit" value. If anything, it seems like an Android-speficic extension of constants similar to those specified as runtime invariant in SUS.The
M_MMAP_MAXandM_ARENA_MAXLinux constants were not found in the Linux source tree, so I have decided against their deprecation. I looked underinclude/uapi/linux/personality.hand didn't find anything. Then I looked into the glibc repo, and could neither find anything.The
IFSTATMAXandTCP_FUNCTION_NAME_LEN_MAXconstants in the FreeBSD source tree have been deprecated as the comments and context in their upstream definitions mention them as being used for character array sizes in fields of records declared near them. I believe this fits the type of "limit" value we're looking to deprecate.The
TCP_BBR_PACE_SEG_MAXconstant in FreeBSD has been left unmodified, because I couldn't find any context nor explanation on its purpose. The source code itself defines it as an unused constant.The
PRI_MAXconstant in FreeBSD has been deprecated, though I am not very sure of this one. It seems as if the range could change by the comment that precedes it and other related constants, but that may not be the case. One could interpret that the range bound to change is that of idle user threads, but I'm not sure. Outside input on this would be greatly appreciated.The
SCTP_PR_SCTP_MAXandSCTP_ASSOC_SUPPORTS_MAXconstants in FreeBSD (the former also in Linux) have been deprecated as they are used to denote the largest value among constants defined prior to them in an enum-like manner. This seems to fit the type of "limit" value we are looking to deprecate.The
EAI_MAXconstant in the Newlib tree has been deprecated because it also fits the trailing enum-like largest value mentioned in prior items.The
_PTHREAD_SHARED_SEM_NAME_MAXconstant in VxWorks got deprecated as the comment alongside its declaration implies it is used solely as a limit to character arrays for synchronization utilities. This seems like it fits the type of "limit" we would want to deprecate. Sources can be found in the VxWorks SDK for QEMU on x86_64.The
_PARM_NAME_MAXand_PARM_PATH_MAXconstants in VxWorks got deprecated because they seem to attempt to replicate the analogous, POSIX-compliant_POSIX_NAME_MAXand_POSIX_PATH_MAX, but using non-standard-compliant parameters set by them. The POSIX constants don't get deprecated because they're meant to provide a guarantee on the on the lower/upper bound of the constant they're referring, but these VxWorks-specific bounds do not seem to be backed by a standard, so I went ahead and deprecated them. Sources can be found in the downloadable SDKs for QEMU on x86_64.Much like in Android (as noted in one of the above items,) the
PR_SCHED_CORE_MAXconstant is used as a trailing maximum value for a set of constants delcared right before it in the Linux kernel's UAPI. This constant has thus been deprecated.I couldn't find the
RT_CLASS_MAXconstant in neither of the Linux nor L4RE upstream repos, but I still decided to deprecate it as in our own sources (thelibccrate) it appears to be a trailing enum-like value for the largest of some constants defined prior to it.The
SKF_AD_MAXconstant in Linux has been deprecated as is used as trailing enum-like value denoting the largest of the "variants" declared before it.The following constants in Linux:
IW_ENCODING_TOKEN_MAX,IW_POWER_MAX,IW_RETRY_MAX,IW_CUSTOM_MAX,IW_GENERIC_IE_MAX,KERN_RTSIGMAX,KERN_SHMMAX,KERN_MSGMAX,SCHED_FLAG_UTIL_CLAMP_MAXhave not been deprecated because they seem to be used as genuine maximum values unlikely to be changed, though I'm judging solely by the comments left alongside them and the overall context in the source code.
The
FILNAME_MAXconstant on Illumos has been deprecated as it was used as the array size for a field of a record declared right after it.The
TCP_RTO_MAXandPPS_SHIFTMAXin for Solarish-like systems constants were left undeprecated, as they denote a limit but they don't quite strike me like the types of values that would easily break SemVer.Checklist
libc-test/semverhave been updated*LASTor*MAXare included (see #3131)cd libc-test && cargo test --target mytarget); especially relevant for platforms that may not be checked in CI@rustbot label +stable-nominated