FDRef - Revision history

Kevin Reid: link to info about choice of “open file”

Kevin Reid — Mon, 25 Jul 2011 13:48:37 GMT

link to info about choice of “open file”

New page

:''This object type is currently only implemented in [[E-on-CL]].''

An [[FDRef]] is an object which wraps the operating system's ''file descriptors'' or similar objects. On platforms which have file descriptors, i.e. small integers naming [http://unix.stackexchange.com/questions/11373/what-is-the-referent-of-a-file-descriptor open files], the primary purpose of FDRef objects is to ensure that a file descriptor is closed after, and not before, there are no users of it (that is, when the FDRef is garbage collected). Therefore, all interfaces to system calls which take file descriptors should either take FDRefs or be methods of FDRef.

FDRefs are a low-level interface; they reveal nondeterminism, and may be used to directly perform potentially blocking system calls. They should always be wrapped by higher-level facilities, and exist only to be a useful implementation abstraction and to allow writing said wrappers in E.

Since file descriptors may be explicitly closed, it is possible to have a FDRef which is ''invalid'' — having no associated file descriptor.

==Protocol==

When a method is applicable to only certain types of open files (e.g. shutdown only applies to sockets), it may be absent from that particular FDRef object. '''Note''': Due to limitations caused by the implementation platform, it may be the case that a FDRef does not have all of the methods it should for its file type if it was obtained in some “generic” way, or it may have methods which are not applicable. {{XXX|Should we obligate implementing [[Miranda respondsTo|__respondsTo/2]] to detect the type of file?}}

{{XXX|finish documenting/specifying. Add all the socket-specific methods from EoCL}}

{{XXX|Write a single page documenting system call error code conversions to exceptions.}}

{{instance msgdoc|close|1|<var>ejector</var> :[[ExitFunc]]|[[void]]}}

Performs the {{SUSfn|close}} system call, exiting according to <var>ejector</var> if it fails, and marks this FDRef invalid.

{{XXX|What should happen to the state of the FDRef in the event of failure? Is it possible for the FD to not have been deallocated.}}

{{instance msgdoc|getFD|0||[[int]]}}

Returns the file descriptor, throwing if this FDRef is invalid. Clients should be extremely careful to retain the FDRef until they are done using the file descriptor, and must rely on other clients of this FDRef not to close it.

{{instance msgdoc|shutdown|2|<var>direction</var> :XXX, <var>ejector</var> :[[ExitFunc]]|[[void]]}}

Performs the {{SUSfn|shutdown}} system call, exiting according to <var>ejector</var> if it fails. {{XXX|Explain direction argument. In current impl, it is a CL symbol.}}

{{instance msgdoc|write|2|<var>data</var> :[[ConstList]], <var>ejector</var> :[[ExitFunc]], <var>start</var> :[[int]], <var>length</var> :{{sub|[[nullOK]]|[[int]]}}|[[void]]}}

Performs the {{SUSfn|write}} system call, exiting according to <var>ejector</var> if it fails. Any resulting <code>SIGPIPE</code> is ignored.

If <var>length</var> is null, then the length of <var>data</var> is used. {{XXX|Better ''length-start''?}}

{{instance msgdoc|read|2|<var>maxOctets</var> :[[int]] ≥ 0, <var>errorEjector</var> :[[ExitFunc]], <var>eofEjector</var> :[[ExitFunc]]|[[ConstList]]}}

Performs the {{SUSfn|read}} system call.

* If read() returns a positive number, the octets read are returned in a [[ConstList]].
* If read() returns 0 (end of file), <var>eofEjector</var> is invoked. {{XXX|specify argument to ejector}}
* If read() returns -1,
** If the error is EWOULDBLOCK, [] is returned.
** Otherwise <var>errorEjector</var> is invoked.

The return value is the list of octets read.

[[Category:EIO]]
[[Category:ELib specification]]

Kevin Reid: all non-socket EoCL fd-ref methods now documented

Kevin Reid — Mon, 25 Jul 2011 04:47:27 GMT

all non-socket EoCL fd-ref methods now documented

←Older revision		Revision as of 04:47, 25 July 2011
Line 5:		Line 5:
	FDRefs are a low-level interface; they reveal nondeterminism, and may be used to directly perform potentially blocking system calls. They should always be wrapped by higher-level facilities, and exist only to be a useful implementation abstraction and to allow writing said wrappers in E.		FDRefs are a low-level interface; they reveal nondeterminism, and may be used to directly perform potentially blocking system calls. They should always be wrapped by higher-level facilities, and exist only to be a useful implementation abstraction and to allow writing said wrappers in E.

-	Since file descriptors may be explicitly closed, it is possible to have a FDRef	+	Since file descriptors may be explicitly closed, it is possible to have a FDRef which is ''invalid'' — having no associated file descriptor.

	==Protocol==		==Protocol==
Line 11:		Line 11:
	When a method is applicable to only certain types of open files (e.g. shutdown only applies to sockets), it may be absent from that particular FDRef object. '''Note''': Due to limitations caused by the implementation platform, it may be the case that a FDRef does not have all of the methods it should for its file type if it was obtained in some “generic” way, or it may have methods which are not applicable. {{XXX\|Should we obligate implementing [[Miranda respondsTo\|__respondsTo/2]] to detect the type of file?}}		When a method is applicable to only certain types of open files (e.g. shutdown only applies to sockets), it may be absent from that particular FDRef object. '''Note''': Due to limitations caused by the implementation platform, it may be the case that a FDRef does not have all of the methods it should for its file type if it was obtained in some “generic” way, or it may have methods which are not applicable. {{XXX\|Should we obligate implementing [[Miranda respondsTo\|__respondsTo/2]] to detect the type of file?}}

-	{{XXX\|finish documenting/specifying}}	+	{{XXX\|finish documenting/specifying. Add all the socket-specific methods from EoCL}}
		+
		+	{{XXX\|Write a single page documenting system call error code conversions to exceptions.}}
		+
		+	{{instance msgdoc\|close\|1\|<var>ejector</var> :[[ExitFunc]]\|[[void]]}}
		+
		+	Performs the {{SUSfn\|close}} system call, exiting according to <var>ejector</var> if it fails, and marks this FDRef invalid.
		+
		+	{{XXX\|What should happen to the state of the FDRef in the event of failure? Is it possible for the FD to not have been deallocated.}}

	{{instance msgdoc\|getFD\|0\|\|[[int]]}}		{{instance msgdoc\|getFD\|0\|\|[[int]]}}
-	~~Returns the file descriptor. Clients should be extremely careful to retain the FDRef until they are done using the file descriptor.~~

-	{{instance msgdoc\|shutdown\|2\|<var>direction</var> :{{XXX~~\|specify}}~~, <var>ejector</var> :[[ExitFunc]]\|[[void]]}}	+	Returns the file descriptor, throwing if this FDRef is invalid. Clients should be extremely careful to retain the FDRef until they are done using the file descriptor, and must rely on other clients of this FDRef not to close it.
		+
		+	{{instance msgdoc\|shutdown\|2\|<var>direction</var> :XXX, <var>ejector</var> :[[ExitFunc]]\|[[void]]}}
		+
	Performs the {{SUSfn\|shutdown}} system call, exiting according to <var>ejector</var> if it fails. {{XXX\|Explain direction argument. In current impl, it is a CL symbol.}}		Performs the {{SUSfn\|shutdown}} system call, exiting according to <var>ejector</var> if it fails. {{XXX\|Explain direction argument. In current impl, it is a CL symbol.}}
		+
		+	{{instance msgdoc\|write\|2\|<var>data</var> :[[ConstList]], <var>ejector</var> :[[ExitFunc]], <var>start</var> :[[int]], <var>length</var> :{{sub\|[[nullOK]]\|[[int]]}}\|[[void]]}}
		+
		+	Performs the {{SUSfn\|write}} system call, exiting according to <var>ejector</var> if it fails. Any resulting <code>SIGPIPE</code> is ignored.
		+
		+	If <var>length</var> is null, then the length of <var>data</var> is used. {{XXX\|Better ''length-start''?}}
		+
		+	{{instance msgdoc\|read\|2\|<var>maxOctets</var> :[[int]] ≥ 0, <var>errorEjector</var> :[[ExitFunc]], <var>eofEjector</var> :[[ExitFunc]]\|[[ConstList]]}}
		+
		+	Performs the {{SUSfn\|read}} system call.
		+
		+	* If read() returns a positive number, the octets read are returned in a [[ConstList]].
		+	* If read() returns 0 (end of file), <var>eofEjector</var> is invoked. {{XXX\|specify argument to ejector}}
		+	* If read() returns -1,
		+	** If the error is EWOULDBLOCK, [] is returned.
		+	** Otherwise <var>errorEjector</var> is invoked.
		+
		+	The return value is the list of octets read.

	[[Category:EIO]]		[[Category:EIO]]
	[[Category:ELib specification]]		[[Category:ELib specification]]

Kevin Reid: save WIP

Kevin Reid — Mon, 25 Jul 2011 04:20:50 GMT

save WIP

←Older revision		Revision as of 04:20, 25 July 2011
Line 2:		Line 2:

	An [[FDRef]] is an object which wraps the operating system's ''file descriptors'' or similar objects. On platforms which have file descriptors, i.e. small integers naming open files, the primary purpose of FDRef objects is to ensure that a file descriptor is closed after, and not before, there are no users of it (that is, when the FDRef is garbage collected). Therefore, all interfaces to system calls which take file descriptors should either take FDRefs or be methods of FDRef.		An [[FDRef]] is an object which wraps the operating system's ''file descriptors'' or similar objects. On platforms which have file descriptors, i.e. small integers naming open files, the primary purpose of FDRef objects is to ensure that a file descriptor is closed after, and not before, there are no users of it (that is, when the FDRef is garbage collected). Therefore, all interfaces to system calls which take file descriptors should either take FDRefs or be methods of FDRef.
		+
		+	FDRefs are a low-level interface; they reveal nondeterminism, and may be used to directly perform potentially blocking system calls. They should always be wrapped by higher-level facilities, and exist only to be a useful implementation abstraction and to allow writing said wrappers in E.
		+
		+	Since file descriptors may be explicitly closed, it is possible to have a FDRef

	==Protocol==		==Protocol==

-	When a method is applicable to only certain types of open files (e.g. shutdown only applies to sockets), it may be absent from that particular FDRef object. '''Note''': Due to limitations caused by the implementation platform, it may be the case that a FDRef does not have all of the methods it should for its file type if it was obtained in some “generic” way, or it may have methods which are not applicable. {{XXX\|Should we obligate implementing ~~{{msg\|~~respondsTo/2}} to detect the type of file?}}	+	When a method is applicable to only certain types of open files (e.g. shutdown only applies to sockets), it may be absent from that particular FDRef object. '''Note''': Due to limitations caused by the implementation platform, it may be the case that a FDRef does not have all of the methods it should for its file type if it was obtained in some “generic” way, or it may have methods which are not applicable. {{XXX\|Should we obligate implementing [[Miranda respondsTo\|__respondsTo/2]] to detect the type of file?}}
		+
		+	{{XXX\|finish documenting/specifying}}
		+
		+	{{instance msgdoc\|getFD\|0\|\|[[int]]}}
		+	Returns the file descriptor. Clients should be extremely careful to retain the FDRef until they are done using the file descriptor.

-	{{XXX}}	+	{{instance msgdoc\|shutdown\|2\|<var>direction</var> :{{XXX\|specify}}, <var>ejector</var> :[[ExitFunc]]\|[[void]]}}
		+	Performs the {{SUSfn\|shutdown}} system call, exiting according to <var>ejector</var> if it fails. {{XXX\|Explain direction argument. In current impl, it is a CL symbol.}}

	[[Category:EIO]]		[[Category:EIO]]
	[[Category:ELib specification]]		[[Category:ELib specification]]

Kevin Reid: draft...

Kevin Reid — Mon, 25 Jul 2011 04:09:29 GMT

draft...

←Older revision		Revision as of 04:09, 25 July 2011
Line 1:		Line 1:
	:''This object type is currently only implemented in [[E-on-CL]].''		:''This object type is currently only implemented in [[E-on-CL]].''

-	An [[FDRef]] is an object which wraps the operating system's ''file descriptors'' or similar objects. On platforms which have file descriptors, i.e. small integers naming ~~[http://unix.stackexchange.com/questions/11373/what-is-the-referent-of-a-file-descriptor~~ open files], the primary purpose of FDRef objects is to ensure that a file descriptor is closed after, and not before, there are no users of it (that is, when the FDRef is garbage collected). Therefore, all interfaces to system calls which take file descriptors should either take FDRefs or be methods of FDRef.	+	An [[FDRef]] is an object which wraps the operating system's ''file descriptors'' or similar objects. On platforms which have file descriptors, i.e. small integers naming open files, the primary purpose of FDRef objects is to ensure that a file descriptor is closed after, and not before, there are no users of it (that is, when the FDRef is garbage collected). Therefore, all interfaces to system calls which take file descriptors should either take FDRefs or be methods of FDRef.
-		+
-	FDRefs are a low-level interface; they reveal nondeterminism, and may be used to directly perform potentially blocking system calls. They should always be wrapped by higher-level facilities, and exist only to be a useful implementation abstraction and to allow writing said wrappers in E.	+
-		+
-	~~Since file descriptors may be explicitly closed, it is possible to have a FDRef which is ''invalid'' — having no associated file descriptor~~.	+

	==Protocol==		==Protocol==

-	When a method is applicable to only certain types of open files (e.g. shutdown only applies to sockets), it may be absent from that particular FDRef object. '''Note''': Due to limitations caused by the implementation platform, it may be the case that a FDRef does not have all of the methods it should for its file type if it was obtained in some “generic” way, or it may have methods which are not applicable. {{XXX\|Should we obligate implementing ~~[[Miranda respondsTo\|__respondsTo/2]] to detect the type of file?}}~~	+	When a method is applicable to only certain types of open files (e.g. shutdown only applies to sockets), it may be absent from that particular FDRef object. '''Note''': Due to limitations caused by the implementation platform, it may be the case that a FDRef does not have all of the methods it should for its file type if it was obtained in some “generic” way, or it may have methods which are not applicable. {{XXX\|Should we obligate implementing {{msg\|respondsTo/2}} to detect the type of file?}}
-		+
-	{{~~XXX~~\|~~finish documenting~~/~~specifying. Add all the socket-specific methods from EoCL~~}}	+
-		+
-	~~{{XXX\|Write a single page documenting system call error code conversions~~ to ~~exceptions.}}~~	+
-		+
-	~~{{instance msgdoc\|close\|1\|<var>ejector</var> :[[ExitFunc]]\|[[void]]}}~~	+
-		+
-	~~Performs~~ the ~~{{SUSfn\|close}} system call, exiting according to <var>ejector</var> if it fails, and marks this FDRef invalid.~~	+
-		+
-	~~{{XXX\|What should happen to the state~~ of ~~the FDRef in the event of failure? Is it possible for the FD to not have been deallocated.}}~~	+
-		+
-	~~{{instance msgdoc\|getFD\|0\|\|[[int]]}}~~	+
-		+
-	~~Returns the~~ file descriptor, throwing if this FDRef is invalid. Clients should be extremely careful to retain the FDRef until they are done using the file descriptor, and must rely on other clients of this FDRef not to close it.	+
-		+
-	~~{{instance msgdoc\|shutdown\|2\|<var>direction</var> :XXX, <var>ejector</var> :[[ExitFunc]]\|[[void]]}}~~	+
-		+
-	~~Performs the {{SUSfn\|shutdown}} system call, exiting according to <var>ejector</var> if it fails. {{XXX\|Explain direction argument. In current impl, it is a CL symbol.}}~~	+
-		+
-	~~{{instance msgdoc\|write\|2\|<var>data</var> :[[ConstList]], <var>ejector</var> :[[ExitFunc]], <var>start</var> :[[int]], <var>length</var> :{{sub\|[[nullOK]]\|[[int]]}}\|[[void]]}}~~	+
-		+
-	~~Performs the {{SUSfn\|write}} system call, exiting according to <var>ejector</var> if it fails. Any resulting <code>SIGPIPE</code> is ignored.~~	+
-		+
-	~~If <var>length</var> is null, then the length of <var>data</var> is used. {{XXX\|Better ''length-start''~~?}}	+
-		+
-	~~{{instance msgdoc\|read\|2\|<var>maxOctets</var> :[[int]] ≥ 0, <var>errorEjector</var> :[[ExitFunc]], <var>eofEjector</var> :[[ExitFunc]]\|[[ConstList]]}}~~	+
-		+
-	~~Performs the {{SUSfn\|read}} system call.~~	+
-		+
-	* If read() returns a positive number, the octets read are returned in a [[ConstList]].	+
-	* If read() returns 0 (end of file), <var>eofEjector</var> is invoked. {{XXX\|specify argument to ejector}}	+
-	* If read() returns -1,	+
-	** If the error is EWOULDBLOCK, [] is returned.	+
-	** Otherwise <var>errorEjector</var> is invoked.	+

-	~~The return value is the list of octets read.~~	+	{{XXX}}

	[[Category:EIO]]		[[Category:EIO]]
	[[Category:ELib specification]]		[[Category:ELib specification]]