﻿/*
	© 2016 FrankHB.

	This file is part of the YSLib project, and may only be used,
	modified, and distributed under the terms of the YSLib project
	license, LICENSE.TXT.  By continuing to use, modify, or distribute
	this file you indicate that you have read the license and
	understand and accept it fully.
*/

/*!	\file Workflow.Annual2016.txt
\ingroup Documentation
\brief 工作流汇总报告 - 2016 年度。
\version r204
\author FrankHB <frankhb1989@gmail.com>
\since build 663
\par 创建时间:
	2016-01-11 09:35:01 +0800
\par 修改时间:
	2016-12-18 19:30 +0800
\par 文本编码:
	UTF-8
\par 模块名称:
	Documentation::Workflow::Annual2016
*/

// See "Meta.cpp" for meta descriptions.

$import $WORKFLOW;
$LINE-WIDTH-RESTRICT 0;

$WORKFLOW:
// Following lines are only for logging informal project information.
// See Meta.txt for formal project information.
// See ChangeLog.*.txt for accepted contents.

$2016-01:

report.impl:
Overloaded function templates for 'std::size' works as expected only with core issue resolutions.
	The overloaded version for array accept non-static member access of array type depends on the change in CWG 616 available in ISO C++14, which forbids it to be a prvalue.
	The deduction for 'std::initializer_list' instance for overloaded version for array depends on the resolution of CWG 1591.

$2016-02:

report.impl:
It is intended that YBase.YStandardEx.Operators classes used in base are publicly derived.
	If only friend functions are used, it does not requires 'public', 'private' can be OK.
		See https://en.wikipedia.org/wiki/Barton–Nackman_trick.
		This is the situation for Boost.Operators and several variants like The Art of C++ / Operators(https://github.com/taocpp/operators)(formally df.operators).
	However, some overloaded operators like 'operator->' and 'operator[]' are only available as member functions.
		Friend declaration is not helpful since they can be used out of the derived classes.
		They are general for iterator overloaded operators.
		Since YBase.YStandardEx.Operators provides such operators, they should be derived with 'public'.
	For simplicity, all classes are derived with 'public', rather than optional 'private' to force users remembering which overloaded operators are used, even it will expose public non-polymorphic bases which should not be used to cast-from.
The allocator '__gnu_cxx::debug_allocator' should not be used.
	Because it is not meet the allocation requirements on non-throwing 'deallocate' member.
	There are generally more powerful and flexible debug methods (e.g. valgrind and DrMemory).
		Even for freestanding implementations without them, memory debugging is still hard with the aid of such allocator rather than cutome ones with desired error handling.

$2016-03:

report.impl:
There are several changes in the library final fundamental TS final draft(WG21 N4480) since WG21 N4081.
	There are several changes for 'optional' requires minor update for return type of member functions.
	The implementation of class 'any' is not effected.
		Note that 'allocator_arg_t' for constructors of 'any' are no longer required, which was not implemented.
		Another change in the specification is explicitly 'is_nothrow_move_constructible_v' noted, which also requires no implementation change.
	The member function 'clear' is removed from class tmeplate 'basic_string_view'. Assignment of empty string view should be used instead.
		See WG21 N4288 (adopted 2014-11) for the modification.
Rules on access specifier for operator bases are amended, based on $2016-02 report.impl.
	Now classes with these bases use 'private' at first, to conform to the general language rules.
	For %iterator_operators_t it is still remained to be 'public' due to possible 'operator[]' and 'operator->' members.
	User code is still not restricted.
WG21 N4279 introduces 'try_emplace' and 'insert_or_assign' for map-like containers. There are some points to be noted.
	Only 'std::map' and 'std::unordered_map' have such interface. Set-like containers do not.
	If needed for set-like containers, it is better to be emulated directly by 'ystdex::try_emplace' and 'ystd::try_emplace_hint' directly because they avoid some significant shortcomings.
		They have less ambiguity (between iterator and key parameter) with generic key type support.
		For overloading with hint, the return value type is richer, i.e. with also 'bool' component to detect whether the insertion has been succeeded.
		They are more generic.
	As emulating 'std::set' rather than 'std::map', 'ystdex::mapped_set' now does not provide such extensions.
		It also avoid heavy dependency on header 'ystdex/container.h'.
	On the other hand, 'YSLib::ValueNode' still provides 'try_emplace', with generic key types support.
		Since it is emulating 'std::map' and non-generic key are too limited.
		To be compatible, overloading with hint is still named as 'try_emplace' and using single iterator return value, with SFINAE detection to avoid ambiguity.
		Some other extensions like typed insertion (for 'ValueNode::Value') are still provided in other names.

$2016-04:

report.impl:
The POSIX function '::close' may return error and set 'errno' to 'EINVAL' or 'EIO', and the state of file descriptor after the call is unspecified.
	See http://pubs.opengroup.org/onlinepubs/9699919799/functions/close.html.
	On some implementations, '::close' and some other function calls may always cause file descriptor to be closed even if returning 'EINTR'.
		See https://www.python.org/dev/peps/pep-0475/#modified-functions.
	Ignoring error handling of '::close' for portable code is a common bug.
		See https://stackoverflow.com/questions/19056309/not-checking-closes-return-value-how-serious-really.
	However, for purpose of resource release (e.g. in destructor), this is intended to be ignored.
		Resource release is designed to not propogate any error to provide no exception guarantee.
		There are no way to handle the errors reliably because these errors are not recoverable in general.
		There are also no way to handle the errors portably. It has been existed in pre-POSIX UNIX implemntations.
			See http://austingroupbugs.net/view.php?id=529.
		For implementation does not guarantee the file descriptor being closed, caller should work around.
			However, the mainstream platforms are all behave like this, or there is even no chance to raise 'EINTR' in call of '::close'.
			Thus YSLib currently does not implement the workaround.
	Further, the API is designed to release resource as the main purpose.
		It is different to others, so special handling of 'EINTR' is acceptable.
	To assume 'EINTR' leaving the file descriptor open and then retry to close it is particular dangerous at least in Linux.
		See http://lwn.net/Articles/576478/. In fact, Linux is hard to raise 'EINTR' here.
		If flush is required, the caller should do it before closing the file descriptor, and '::fsync' call may be needed.

$2016-05:

report.impl:
Android GUI architecture in YFramework has been reviewed in progress.
	Early stage is finished. The remained work is delayed to v0.7. Some conclusions remains vaild.
	It is intended to keep the android native "UI" thread as main thread without full inversion of control by design.
		That is, the original thread in call of '::ANativeActivity_onCreate' has a longer lifetime than main routine call on spawned thread.
		Since this thread partially plays a role like Win32 (GUI) subsystem of 'csrss.exe', it should be lived at any time when a GUI client is running in a system-provided GUI session.
	Current implementation only supports DS window emulation.
		This should be updated to a broader capability even if the native Android GUI does not have a window manager supporting multiple windows like a stacking window manager in general.
		It is implemented using direct binding to 'Desktop' instance as a non-hosted platform (i.e. DS).
		This should be changed using a middle layaer as 'WindowThread' under Win32, to get more flexibility for implementing features in future.
			It can still be 'WindowThread' but without requiring a real thread, since there is only one event loop active at any time in one process.
		Problems remained on design of event loop related APIs, for example:
			A class of loop is generally not needed, but since there is direct "looper" out of the box proveded by Android native API, is it reqired to be wrapped?
			The loop is now implemented in 'AndroidHost' of 'YCLib' Android extensions. Should it also be configurable in 'Helper'?
			It is not clear that which precise sets of functionality should be exposed in 'Helper' and 'YCLib' Android extensions.
		It is also not clear that if it necessary to emulate a window manager between 'YCLib' Android extension and 'Helper'.

$2016-06:

report.impl:
There is one change concerned with FreeType2 not clear yet. That is, loading same typefaces might trigger an error message depending on different version of FreeType.
	On platform 'DS', the error message would be explicitly shown and an extra input was needed to continue the program.
		The message is like 'error: Face request error: 00000090' for same fonts.
			According to "fterrdef.h", the error code 0x90 stands for 'Locations_Missing'.
			In normal cases, this indicates missing location table of specific TrueType typeface in the font file.
		This occurred since b357 due to call to 'platform::YSetDebugStatus'. The error should exist earlier, but not shown.
		This was eliminated since b420 due to update to (modified) FreeType 2.5.0.1 from FreeType 2.4.11.
	Further test shows that this was introduced in FreeType 2.5.0.
		The replaced files for YSLib used had no effect on this issue.
			For the issue worked around, see http://savannah.nongnu.org/bugs/index.php?39383.
		For newer toolchain, the YSLib source may need be patched to make it compile.
			Current version of 'string.h' of YBase.LibDefect should be used.
			For 'iterator.h' in YBase.YStandard, type of data member 'transformer' of class template 'transformed_iterator' need to be decayed.
		FreeType 2.4.12 would not prevent the error message.
		The effective change was introduced in Git commit '760d342d37ec9b26420956e3421075d410571b65' of official repository by Behdad Esfahbod.
			The brief commit message is 'Add support for color embedded bitmaps (eg. color emoji)'.
			Change to file 'src/sfnt/ttsbit.c' caused the behavior change.
		The above change was once (wrongly) suspected to be a side effect and filed as http://savannah.nongnu.org/bugs/index.php?48117.
	The reason is that font may contain CBDT and CBLT (for color emoji) tables which would only be recognized since FreeType 2.5.0. If it does not contain other table, the error trigged as expected.
Alias analysing matters.
	ISO C99 has strict aliasing rules. ISO C++ has more restrictions.
		Void types and character types are ruled out in ISO C. Only 'cv void', 'cv char' and 'cv unsigned char' in ISO C++, however.
			This is why 'ystdex::byte' mandated to be 'unsigned char' but not 'signed char'. (And though 'char' is available, its unspecified signedness may cause unnecessary problems.)
		For object within its lifetime, see [basic.lval]/10; otherwise, see [basic.life]/6, [basic.life]/7 and [basic.life]/8.
			[basic.life]/6 is stricter on 'static_cast'. Only cast sequence essentially to 'reinterpret_cast' to 'cv void', 'cv char' or 'cv unsigned char'.
		Also note 'wchar_t', 'char16_t' and 'char32_t' is distinct to the underlying types. In C, they are just type alias to some integer types.
			This diverges the alias analysis in C and C++.
			For example, on Win32, 'wchar_t' lvalue may be safely accessible through 'unsigned short' pointers. This is not true on C++.
			This may cause trouble in interoperations. Use carefully.
		It is utilized as TBAA(type-based alias analysis) in various implementations, to generate better code.
			GCC 4 enables '-fstrict-aliasing' for '-O2' or above, with `__attribute__((may_alias))` to revert it on types other than 'cv char', etc: https://gcc.gnu.org/onlinedocs/gcc-4.0.1/gcc/Type-Attributes.html.
			Clang has implemented TBAA: https://llvm.org/bugs/show_bug.cgi?id=2547, but is lack of 'may_alias' attribute: https://llvm.org/bugs/show_bug.cgi?id=11082.
			So bypassing the restrictions may be not portable anyway in a long time.
		The extra attribute to bypass strict analysing is also considered like type qualifers (as 'const').
			Such rules of the standard is a limitation with mandated 'may_alias' only on several character types, which may be improved in future version of languages or dialects.
		If no aliased value can be used due to the strict aliasing, copying of the stored value in the lvalue may be needed.
		In C++, objects can be dynamically allocated using placement '::new' expressions, though other rules still limit the access on the underlying storage.
			The underlying object does not need to be array of 'cv char'.
	ISO C99 has 'restrict' to ease alias analysis.
		This is not type-based. However, violation of it also causes undefined behavior.
		This imporves the performance of carefully written C programs, comparing with FORTRAN programs.
		C++ has no similar features except for similar extension in dialects, typically spelled as '__restrict'.

$2016-08:

report.impl:
The standard library class "std::nested_exception" only takes currently handled exception.
	So there is lack of efficient way to create a nested exception object to be thrown.
	Stick on try-block, throw, catch and then call "std::throw_with_nested" instead.
		Use proper macros to ease the work in YFramework.
Now external file accessed by YFramework (including the configuration 'yconf.txt') uses file locking in hosted environments.
	Combined with file opening atomicity improvement, this reduced some race conditions.
	However, TOCTTOU access can still not be totally fixed.
		See https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use#Preventing_TOCTTOU.
	See also $2015-09 report.impl.

$2016-09:

report.impl:
In YSLib, bare passive clause is preferred for exception message or other error handling messages, besides those in assertion strings, etc.
	See also $2014-08 report.impl.

$2016-12:

report.impl:
Note the standard does specify that 'std::allocator' may differ with new/delete.
	Avoid mix new/delete with allocator.
		Especially be cautious to default deleters in smart pointers.
	Current libc++ does it theoretically wrongly in the large handler in <experimental/any>.
		Although the behavior can still be expected when 'std::allocator' is provided by libc++, which should be normal.
There are some troubles with Windows 10 rs2_prerelease console output.
	Buffered MBCS-oriented stream cannot interact well within the console.
		However, wide-oriented console output works.
		It seems that the underlying implementation would assume wrong width (number of bytes) of a multibyte character.
	It can be worked around by disabling the CRT buffering on the stream.
		The 'stdout' is buffered by default.
		The standard 'std::setvbuf' with '_IONBF' works.
		The call of 'std::ios_base::sync_with_stdio({})' also works, but it has side effects on console color setting.
			Notably, the '::SetConsoleTextAttribute' call of setting foreground color would have effect on the whole line instead of the output text after the call.

////

